Skip to content

Commit eb24b9c

Browse files
megothmegoth
committed
Adding back description of @PARAM and @returns 
1 parent 681ed10 commit eb24b9c

1 file changed

Lines changed: 87 additions & 4 deletions

File tree

‎src/authn/authn.ts‎

Lines changed: 87 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -32,6 +32,29 @@ export function findOriginOwner (doc: $rdf.NamedNode | string): string | boolean
3232
return origin
3333
}
3434

35+
// Promises versions
36+
//
37+
// These pass a context object which hold various RDF symbols
38+
// as they become available
39+
//
40+
// me RDF symbol for the users' webid
41+
// publicProfile The user's public profile, iff loaded
42+
// preferencesFile The user's personal preferences file, iff loaded
43+
// index.public The user's public type index file
44+
// index.private The user's private type index file
45+
// not RDF symbols:
46+
// noun A string in english for the type of thing -- like "address book"
47+
// instance An array of nodes which are existing instances
48+
// containers An array of nodes of containers of instances
49+
// div A DOM element where UI can be displayed
50+
// statusArea A DOM element (opt) progress stuff can be displayed, or error messages
51+
52+
/**
53+
* @param webId
54+
* @param context
55+
*
56+
* @returns Returns the Web ID, after setting it
57+
*/
3558
export function saveUser (
3659
webId: $rdf.NamedNode | string,
3760
context?: AuthenticationContext
@@ -49,6 +72,9 @@ export function saveUser (
4972
return null
5073
}
5174

75+
/**
76+
* @returns {NamedNode|null}
77+
*/
5278
export function defaultTestUser (): $rdf.NamedNode | null {
5379
// Check for offline override
5480
const offlineId = offlineTestID()
@@ -60,8 +86,9 @@ export function defaultTestUser (): $rdf.NamedNode | null {
6086
return null
6187
}
6288

63-
/**
64-
* Checks synchronously whether user is logged in
89+
/** Checks syncronously whether user is logged in
90+
*
91+
* @returns Named Node or null
6592
*/
6693
export function currentUser (): $rdf.NamedNode | null {
6794
const str = localStorage['solid-auth-client']
@@ -78,6 +105,8 @@ export function currentUser (): $rdf.NamedNode | null {
78105

79106
/**
80107
* Resolves with the logged in user's Web ID
108+
*
109+
* @param context
81110
*/
82111
export function logIn (context: AuthenticationContext): Promise<AuthenticationContext> {
83112
const me = defaultTestUser() // me is a NamedNode or null
@@ -109,6 +138,10 @@ export function logIn (context: AuthenticationContext): Promise<AuthenticationCo
109138

110139
/**
111140
* Logs the user in and loads their WebID profile document into the store
141+
*
142+
* @param context
143+
*
144+
* @returns Resolves with the context after login / fetch
112145
*/
113146
export function logInLoadProfile (context: AuthenticationContext): Promise<AuthenticationContext> {
114147
if (context.publicProfile) {
@@ -152,6 +185,10 @@ export function logInLoadProfile (context: AuthenticationContext): Promise<Authe
152185
/**
153186
* Loads preferences file
154187
* Do this after having done log in and load profile
188+
*
189+
* @private
190+
*
191+
* @param context
155192
*/
156193
export function logInLoadPreferences (context: AuthenticationContext): Promise<AuthenticationContext> {
157194
if (context.preferencesFile) return Promise.resolve(context) // already done
@@ -697,6 +734,11 @@ export function registrationList (context: AuthenticationContext, options: {
697734
* RWC for the owner, and a specified access (default none) for the public.
698735
* In all cases owner has read write control.
699736
* Parameter lists modes allowed to public
737+
*
738+
* @param options
739+
* @param options.public eg ['Read', 'Write']
740+
*
741+
* @returns Resolves with aclDoc uri on successful write
700742
*/
701743
export function setACLUserPublic (
702744
docURI: $rdf.NamedNode,
@@ -739,6 +781,10 @@ export function setACLUserPublic (
739781
})
740782
}
741783

784+
/**
785+
* @param docURI
786+
* @returns
787+
*/
742788
function fetchACLRel (docURI: $rdf.NamedNode): Promise<$rdf.NamedNode> {
743789
const fetcher = kb.fetcher
744790

@@ -760,6 +806,14 @@ function fetchACLRel (docURI: $rdf.NamedNode): Promise<$rdf.NamedNode> {
760806
})
761807
}
762808

809+
/**
810+
* @param docURI
811+
* @param me
812+
* @param aclURI
813+
* @param options
814+
*
815+
* @returns Serialized ACL
816+
*/
763817
function genACLText (
764818
docURI: $rdf.NamedNode,
765819
me: $rdf.NamedNode,
@@ -834,9 +888,18 @@ function getDefaultSignInButtonStyle (): string {
834888
return 'padding: 1em; border-radius:0.5em; margin: 2em; font-size: 100%;'
835889
}
836890

891+
/**
892+
* Bootstrapping identity
893+
* (Called by `loginStatusBox()`)
894+
*
895+
* @param dom
896+
* @param setUserCallback
897+
*
898+
* @returns
899+
*/
837900
function signInOrSignUpBox (
838901
dom: HTMLDocument,
839-
setUserCallback: Function,
902+
setUserCallback: (user: string) => void,
840903
options: {
841904
buttonStyle?: string
842905
} = {}
@@ -925,6 +988,11 @@ function checkCurrentUser () {
925988
}
926989
*/
927990

991+
/**
992+
* @param [setUserCallback] Optional callback
993+
*
994+
* @returns Resolves with web id uri, if no callback provided
995+
*/
928996
export function checkUser<T> (
929997
setUserCallback?: (me: $rdf.NamedNode | null) => T
930998
): Promise<$rdf.NamedNode | T> {
@@ -960,10 +1028,15 @@ export function checkUser<T> (
9601028
* Login status box
9611029
*
9621030
* A big sign-up/sign in box or a logout box depending on the state
1031+
*
1032+
* @param dom
1033+
* @param listener
1034+
*
1035+
* @returns
9631036
*/
9641037
export function loginStatusBox (
9651038
dom: HTMLDocument,
966-
listener: Function | null = null,
1039+
listener: ((uri: string) => void) | null = null,
9671040
options: {
9681041
buttonStyle?: string
9691042
} = {}
@@ -1081,6 +1154,10 @@ export function loginStatusBox (
10811154
* - Allows the user to just type in a URI by hand
10821155
*
10831156
* Calls back with the ws and the base URI
1157+
*
1158+
* @param dom
1159+
* @param appDetails
1160+
* @param callbackWS
10841161
*/
10851162
export function selectWorkspace (
10861163
dom: HTMLDocument,
@@ -1286,6 +1363,12 @@ export function selectWorkspace (
12861363
*
12871364
* An instance of an app could be e.g. an issue tracker for a given project,
12881365
* or a chess game, or calendar, or a health/fitness record for a person.
1366+
*
1367+
* @param dom
1368+
* @param appDetails
1369+
* @param callback
1370+
*
1371+
* @returns A div with a button in it for making a new app instance
12891372
*/
12901373
export function newAppInstance (
12911374
dom: HTMLDocument,

0 commit comments

Comments
 (0)