diff --git a/eslint/general.js b/eslint/general.js index 5e39dab2e..182f806ec 100644 --- a/eslint/general.js +++ b/eslint/general.js @@ -51,8 +51,16 @@ module.exports = { 'import/extensions': 'error', 'import/no-extraneous-dependencies': 'error', + 'jsdoc/tag-lines': [ 'error', 'any', { startLines: 1 }], 'jsdoc/no-multi-asterisks': [ 'error', { allowWhitespace: true }], 'jsdoc/no-types': 'error', + 'jsdoc/sort-tags': [ 'error', { + tagSequence: [ + { tags: [ 'param' ]}, + { tags: [ 'returns' ]}, + { tags: [ 'throws' ]}, + ], + }], 'jsdoc/valid-types': 'error', 'node/prefer-global/buffer': [ 'error', 'always' ], diff --git a/scripts/finalizeRelease.ts b/scripts/finalizeRelease.ts index d3584b3ab..5826f093b 100644 --- a/scripts/finalizeRelease.ts +++ b/scripts/finalizeRelease.ts @@ -27,7 +27,9 @@ async function commitAndTag(): Promise { /** * Prompts the user for input + * * @param query - A string to prompt the user + * * @returns Promise with the input of the user */ async function waitForUserInput(query: string): Promise { diff --git a/scripts/formatChangelog.ts b/scripts/formatChangelog.ts index d95b45d55..266d6b664 100644 --- a/scripts/formatChangelog.ts +++ b/scripts/formatChangelog.ts @@ -14,7 +14,9 @@ import { readFile, writeFile } from 'fs-extra'; /** * Capitalize all list entries + * * @param input - String to search/replace + * * @returns Promise with output string */ async function capitalizeListEntries(input: string): Promise { @@ -31,7 +33,9 @@ function endProcess(error: Error): never { /** * Main function for changelog formatting + * * @param filePath - Path to the changelog file + * * @returns Promise */ async function formatChangelog(filePath: string): Promise { diff --git a/scripts/upgradeConfig.ts b/scripts/upgradeConfig.ts index 6ed86b6f5..94c2ab68a 100644 --- a/scripts/upgradeConfig.ts +++ b/scripts/upgradeConfig.ts @@ -18,6 +18,7 @@ import { joinFilePath, readPackageJson } from '../src/util/PathUtil'; /** * Search and replace the version of a component with given name + * * @param filePath - File to search/replace * @param regex - RegExp matching the component reference * @param version - Semantic version to change to @@ -31,8 +32,10 @@ async function replaceComponentVersion(filePath: string, regex: RegExp, version: /** * Recursive search for files that match a given Regex + * * @param path - Path of folder to start search in * @param regex - A regular expression to which file names will be matched + * * @returns Promise with all file pathss */ async function getFilePaths(path: string, regex: RegExp): Promise { diff --git a/src/authorization/AcpReader.ts b/src/authorization/AcpReader.ts index bc7ca9dcf..80b4d3f6e 100644 --- a/src/authorization/AcpReader.ts +++ b/src/authorization/AcpReader.ts @@ -65,6 +65,7 @@ export class AcpReader extends PermissionReader { /** * Generates the allowed permissions. + * * @param target - Target to generate permissions for. * @param credentials - Credentials that are trying to access the resource. * @param resourceCache - Cache used to store ACR data. diff --git a/src/authorization/AcpUtil.ts b/src/authorization/AcpUtil.ts index 8883c0cbf..41c8f8fc2 100644 --- a/src/authorization/AcpUtil.ts +++ b/src/authorization/AcpUtil.ts @@ -27,6 +27,7 @@ function getObjectValues(data: Store, subject: Term, predicate: NamedNode): stri /** * Finds the {@link IMatcher} with the given identifier in the given dataset. + * * @param data - Dataset to look in. * @param matcher - Identifier of the matcher. */ @@ -42,6 +43,7 @@ export function getMatcher(data: Store, matcher: Term): IMatcher { /** * Finds the {@link IPolicy} with the given identifier in the given dataset. + * * @param data - Dataset to look in. * @param policy - Identifier of the policy. */ @@ -58,6 +60,7 @@ export function getPolicy(data: Store, policy: Term): IPolicy { /** * Finds the {@link IAccessControl} with the given identifier in the given dataset. + * * @param data - Dataset to look in. * @param accessControl - Identifier of the access control. */ @@ -71,6 +74,7 @@ export function getAccessControl(data: Store, accessControl: Term): IAccessContr /** * Finds the {@link IAccessControlResource} with the given identifier in the given dataset. + * * @param data - Dataset to look in. * @param acr - Identifier of the access control resource. */ @@ -88,6 +92,7 @@ export function getAccessControlResource(data: Store, acr: Term): IAccessControl /** * Finds all {@link IAccessControlledResource} in the given dataset. + * * @param data - Dataset to look in. */ export function* getAccessControlledResources(data: Store): Iterable { diff --git a/src/authorization/PermissionBasedAuthorizer.ts b/src/authorization/PermissionBasedAuthorizer.ts index a48c9d305..ffcdc5b92 100644 --- a/src/authorization/PermissionBasedAuthorizer.ts +++ b/src/authorization/PermissionBasedAuthorizer.ts @@ -24,6 +24,7 @@ export class PermissionBasedAuthorizer extends Authorizer { /** * The existence of the target resource determines the output status code for certain situations. * The provided {@link ResourceSet} will be used for that. + * * @param resourceSet - {@link ResourceSet} that can verify the target resource existence. */ public constructor(resourceSet: ResourceSet) { @@ -77,6 +78,7 @@ export class PermissionBasedAuthorizer extends Authorizer { * Ensures that at least one of the credentials provides permissions for the given mode. * Throws a {@link ForbiddenHttpError} or {@link UnauthorizedHttpError} depending on the credentials * if access is not allowed. + * * @param credentials - Credentials that require access. * @param permissionSet - PermissionSet describing the available permissions of the credentials. * @param mode - Which mode is requested. @@ -98,6 +100,7 @@ export class PermissionBasedAuthorizer extends Authorizer { /** * Checks whether the agent is authenticated (logged in) or not (public/anonymous). + * * @param credentials - Credentials to check. */ private isAuthenticated(credentials: Credentials): boolean { diff --git a/src/authorization/WebAclReader.ts b/src/authorization/WebAclReader.ts index 1d83110ed..8087da2cc 100644 --- a/src/authorization/WebAclReader.ts +++ b/src/authorization/WebAclReader.ts @@ -96,6 +96,7 @@ export class WebAclReader extends PermissionReader { /** * Determines the available permissions for the given credentials. + * * @param acl - Store containing all relevant authorization triples. * @param credentials - Credentials to find the permissions for. */ @@ -223,6 +224,7 @@ export class WebAclReader extends PermissionReader { /** * Extracts all rules from the store that are relevant for the given target, * based on either the `acl:accessTo` or `acl:default` predicates. + * * @param store - Store to filter. * @param target - The identifier of which the acl rules need to be known. * @param directAcl - If the store contains triples from the direct acl resource of the target or not. diff --git a/src/authorization/access/AgentGroupAccessChecker.ts b/src/authorization/access/AgentGroupAccessChecker.ts index 957956bde..a65020292 100644 --- a/src/authorization/access/AgentGroupAccessChecker.ts +++ b/src/authorization/access/AgentGroupAccessChecker.ts @@ -29,6 +29,7 @@ export class AgentGroupAccessChecker extends AccessChecker { /** * Checks if the given agent is member of a given vCard group. + * * @param webId - WebID of the agent that needs access. * @param group - URL of the vCard group that needs to be checked. * diff --git a/src/authorization/permissions/IntermediateCreateExtractor.ts b/src/authorization/permissions/IntermediateCreateExtractor.ts index 646fa229a..36292033a 100644 --- a/src/authorization/permissions/IntermediateCreateExtractor.ts +++ b/src/authorization/permissions/IntermediateCreateExtractor.ts @@ -19,6 +19,7 @@ export class IntermediateCreateExtractor extends ModesExtractor { /** * Certain permissions depend on the existence of the target resource. * The provided {@link ResourceSet} will be used for that. + * * @param resourceSet - {@link ResourceSet} that can verify the target resource existence. * @param strategy - {@link IdentifierStrategy} that will be used to determine parent containers. * @param source - The source {@link ModesExtractor}. diff --git a/src/authorization/permissions/MethodModesExtractor.ts b/src/authorization/permissions/MethodModesExtractor.ts index 5a581ca14..6744e90d8 100644 --- a/src/authorization/permissions/MethodModesExtractor.ts +++ b/src/authorization/permissions/MethodModesExtractor.ts @@ -20,6 +20,7 @@ export class MethodModesExtractor extends ModesExtractor { /** * Certain permissions depend on the existence of the target resource. * The provided {@link ResourceSet} will be used for that. + * * @param resourceSet - {@link ResourceSet} that can verify the target resource existence. */ public constructor(resourceSet: ResourceSet) { diff --git a/src/authorization/permissions/N3PatchModesExtractor.ts b/src/authorization/permissions/N3PatchModesExtractor.ts index 8f7bb2ca9..dc217d3db 100644 --- a/src/authorization/permissions/N3PatchModesExtractor.ts +++ b/src/authorization/permissions/N3PatchModesExtractor.ts @@ -22,6 +22,7 @@ export class N3PatchModesExtractor extends ModesExtractor { /** * Certain permissions depend on the existence of the target resource. * The provided {@link ResourceSet} will be used for that. + * * @param resourceSet - {@link ResourceSet} that can verify the target resource existence. */ public constructor(resourceSet: ResourceSet) { diff --git a/src/authorization/permissions/SparqlUpdateModesExtractor.ts b/src/authorization/permissions/SparqlUpdateModesExtractor.ts index 56d789dc7..a26259557 100644 --- a/src/authorization/permissions/SparqlUpdateModesExtractor.ts +++ b/src/authorization/permissions/SparqlUpdateModesExtractor.ts @@ -20,6 +20,7 @@ export class SparqlUpdateModesExtractor extends ModesExtractor { /** * Certain permissions depend on the existence of the target resource. * The provided {@link ResourceSet} will be used for that. + * * @param resourceSet - {@link ResourceSet} that can verify the target resource existence. */ public constructor(resourceSet: ResourceSet) { diff --git a/src/http/auxiliary/AuxiliaryIdentifierStrategy.ts b/src/http/auxiliary/AuxiliaryIdentifierStrategy.ts index 0c2c2b99f..362ea5af3 100644 --- a/src/http/auxiliary/AuxiliaryIdentifierStrategy.ts +++ b/src/http/auxiliary/AuxiliaryIdentifierStrategy.ts @@ -31,6 +31,7 @@ export interface AuxiliaryIdentifierStrategy { * Checks if the input identifier corresponds to an auxiliary resource. * This does not check if that auxiliary resource exists, * only if the identifier indicates that there could be an auxiliary resource there. + * * @param identifier - Identifier to check. * * @returns true if the input identifier points to an auxiliary resource. @@ -40,6 +41,7 @@ export interface AuxiliaryIdentifierStrategy { /** * Returns the identifier of the resource which this auxiliary resource is referring to. * This does not guarantee that this resource exists. + * * @param identifier - Identifier of the auxiliary resource. * * @returns The ResourceIdentifier of the subject resource. diff --git a/src/http/auxiliary/AuxiliaryStrategy.ts b/src/http/auxiliary/AuxiliaryStrategy.ts index d660ca50e..d4f972a48 100644 --- a/src/http/auxiliary/AuxiliaryStrategy.ts +++ b/src/http/auxiliary/AuxiliaryStrategy.ts @@ -11,6 +11,7 @@ import type { AuxiliaryIdentifierStrategy } from './AuxiliaryIdentifierStrategy' export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy { /** * Whether this auxiliary resources uses its own authorization instead of the subject resource authorization. + * * @param identifier - Identifier of the auxiliary resource. */ usesOwnAuthorization: (identifier: ResourceIdentifier) => boolean; @@ -18,6 +19,7 @@ export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy { /** * Whether the root storage container requires this auxiliary resource to be present. * If yes, this means they can't be deleted individually from such a container. + * * @param identifier - Identifier of the auxiliary resource. */ isRequiredInRoot: (identifier: ResourceIdentifier) => boolean; @@ -42,6 +44,7 @@ export interface AuxiliaryStrategy extends AuxiliaryIdentifierStrategy { /** * Validates if the representation contains valid data for an auxiliary resource. * Should throw an error in case the data is invalid. + * * @param identifier - Identifier of the auxiliary resource. * @param representation - Representation of the auxiliary resource. */ diff --git a/src/http/input/metadata/LinkRelParser.ts b/src/http/input/metadata/LinkRelParser.ts index f9d518f3f..6e2c67c86 100644 --- a/src/http/input/metadata/LinkRelParser.ts +++ b/src/http/input/metadata/LinkRelParser.ts @@ -50,7 +50,9 @@ export class LinkRelObject { /** * Checks whether the object can be added to the metadata + * * @param object - The link target. + * * @returns a boolean to indicate whether it can be added to the metadata or not */ private objectAllowed(object: string): boolean { @@ -59,6 +61,7 @@ export class LinkRelObject { /** * Adds the object to the metadata when it is allowed + * * @param object - The link target. * @param metadata - Metadata of the resource. * @param logger - Logger diff --git a/src/http/representation/RepresentationMetadata.ts b/src/http/representation/RepresentationMetadata.ts index e96465752..55271ce82 100644 --- a/src/http/representation/RepresentationMetadata.ts +++ b/src/http/representation/RepresentationMetadata.ts @@ -26,6 +26,7 @@ const cachedNamedNodes: Record = {}; * Converts the incoming name (URI or shorthand) to a named node. * The generated terms get cached to reduce the number of created nodes, * so only use this for internal constants! + * * @param name - Predicate to potentially transform. */ function toCachedNamedNode(name: string): NamedNode { @@ -167,6 +168,7 @@ export class RepresentationMetadata { /** * Helper function to import all entries from the given metadata. * If the new metadata has a different identifier the internal one will be updated. + * * @param metadata - Metadata to import. */ public setMetadata(metadata: RepresentationMetadata): this { @@ -235,6 +237,7 @@ export class RepresentationMetadata { /** * Adds a value linked to the identifier. Strings get converted to literals. + * * @param predicate - Predicate linking identifier to value. * @param object - Value(s) to add. * @param graph - Optional graph of where to add the values to. @@ -245,6 +248,7 @@ export class RepresentationMetadata { /** * Removes the given value from the metadata. Strings get converted to literals. + * * @param predicate - Predicate linking identifier to value. * @param object - Value(s) to remove. * @param graph - Optional graph of where to remove the values from. @@ -271,6 +275,7 @@ export class RepresentationMetadata { /** * Removes all values linked through the given predicate. + * * @param predicate - Predicate to remove. * @param graph - Optional graph where to remove from. */ @@ -300,6 +305,7 @@ export class RepresentationMetadata { /** * Finds all object values matching the given predicate and/or graph. + * * @param predicate - Optional predicate to get the values for. * @param graph - Optional graph where to get from. * @@ -314,10 +320,10 @@ export class RepresentationMetadata { * @param predicate - Predicate to get the value for. * @param graph - Optional graph where the triple should be found. * + * @returns The corresponding value. Undefined if there is no match + * * @throws Error * If there are multiple matching values. - * - * @returns The corresponding value. Undefined if there is no match */ public get(predicate: NamedNode, graph?: MetadataGraph): Term | undefined { const terms = this.getAll(predicate, graph); @@ -337,6 +343,7 @@ export class RepresentationMetadata { /** * Sets the value for the given predicate, removing all other instances. * In case the object is undefined this is identical to `removeAll(predicate)`. + * * @param predicate - Predicate linking to the value. * @param object - Value(s) to set. * @param graph - Optional graph where the triple should be stored. @@ -383,6 +390,7 @@ export class RepresentationMetadata { /** * Parse the internal RDF structure to retrieve the Record with ContentType Parameters. + * * @returns A {@link ContentType} object containing the value and optional parameters if there is one. */ private getContentType(): ContentType | undefined { diff --git a/src/identity/interaction/InteractionUtil.ts b/src/identity/interaction/InteractionUtil.ts index 6c3541884..b1a9621d4 100644 --- a/src/identity/interaction/InteractionUtil.ts +++ b/src/identity/interaction/InteractionUtil.ts @@ -49,6 +49,7 @@ export type AccountInteractionResults = { [ACCOUNT_PROMPT]?: string } & Interact /** * Updates the `oidcInteraction` object with the necessary data in case a prompt gets updated. + * * @param oidcInteraction - Interaction to update. * @param result - New data to add to the interaction. * @param mergeWithLastSubmission - If this new data needs to be merged with already existing data in the interaction. @@ -72,6 +73,7 @@ export async function finishInteraction( * Removes the WebID, the `accountId`, from the OIDC session object, * allowing us to replace it with a new value. * If there is no session in the Interaction, nothing will happen. + * * @param provider - The OIDC provider. * @param oidcInteraction - The current interaction. */ diff --git a/src/identity/interaction/account/util/AccountStore.ts b/src/identity/interaction/account/util/AccountStore.ts index 53f7a6958..d5cc94bd1 100644 --- a/src/identity/interaction/account/util/AccountStore.ts +++ b/src/identity/interaction/account/util/AccountStore.ts @@ -20,6 +20,7 @@ export interface AccountStore { /** * Finds the setting of the account with the given identifier. + * * @param id - The account identifier. * @param setting - The setting to find the value of. */ @@ -27,6 +28,7 @@ export interface AccountStore { /** * Updates the settings for the account with the given identifier to the new values. + * * @param id - The account identifier. * @param setting - The setting to update. * @param value - The new value for the setting. diff --git a/src/identity/interaction/account/util/CookieStore.ts b/src/identity/interaction/account/util/CookieStore.ts index d6ea3c9e8..ed1e178d5 100644 --- a/src/identity/interaction/account/util/CookieStore.ts +++ b/src/identity/interaction/account/util/CookieStore.ts @@ -5,6 +5,7 @@ export interface CookieStore { /** * Generates and stores a new cookie for the given accountId. * This does not replace previously generated cookies. + * * @param accountId - Account to create a cookie for. * * @returns The generated cookie. @@ -13,18 +14,21 @@ export interface CookieStore { /** * Return the accountID associated with the given cookie. + * * @param cookie - Cookie to find the account for. */ get: (cookie: string) => Promise; /** * Refreshes the cookie expiration and returns when it will expire if the cookie exists. + * * @param cookie - Cookie to refresh. */ refresh: (cookie: string) => Promise; /** * Deletes the given cookie. + * * @param cookie - Cookie to delete. */ delete: (cookie: string) => Promise; diff --git a/src/identity/interaction/login/ResolveLoginHandler.ts b/src/identity/interaction/login/ResolveLoginHandler.ts index ddba472a2..6968379c1 100644 --- a/src/identity/interaction/login/ResolveLoginHandler.ts +++ b/src/identity/interaction/login/ResolveLoginHandler.ts @@ -82,6 +82,7 @@ export abstract class ResolveLoginHandler extends JsonInteractionHandler { /** * Updates the account setting that determines if the login status needs to be remembered. + * * @param accountId - ID of the account. * @param remember - If the account should be remembered or not. The setting will not be updated if this is undefined. */ @@ -95,6 +96,7 @@ export abstract class ResolveLoginHandler extends JsonInteractionHandler { /** * Takes the necessary steps to log a user in. + * * @param input - Same input that was passed to the handle function. */ public abstract login(input: JsonInteractionHandlerInput): Promise>; diff --git a/src/identity/interaction/password/util/ForgotPasswordStore.ts b/src/identity/interaction/password/util/ForgotPasswordStore.ts index 2fbd407c1..cd7a47363 100644 --- a/src/identity/interaction/password/util/ForgotPasswordStore.ts +++ b/src/identity/interaction/password/util/ForgotPasswordStore.ts @@ -6,7 +6,9 @@ export interface ForgotPasswordStore { * Creates a Forgot Password Confirmation Record. This will be to remember that * a user has made a request to reset a password. Throws an error if the email doesn't * exist. + * * @param id - ID of the email/password login object. + * * @returns The record id. This should be included in the reset password link. */ generate: (id: string) => Promise; @@ -14,13 +16,16 @@ export interface ForgotPasswordStore { /** * Gets the email associated with the forgot password confirmation record * or undefined if it's not present. + * * @param recordId - The record id retrieved from the link. + * * @returns The user's email. */ get: (recordId: string) => Promise; /** * Deletes the Forgot Password Confirmation Record. + * * @param recordId - The record id of the forgot password confirmation record. */ delete: (recordId: string) => Promise; diff --git a/src/identity/storage/ClientIdAdapterFactory.ts b/src/identity/storage/ClientIdAdapterFactory.ts index 6ec8654c4..879949bb8 100644 --- a/src/identity/storage/ClientIdAdapterFactory.ts +++ b/src/identity/storage/ClientIdAdapterFactory.ts @@ -81,6 +81,7 @@ export class ClientIdAdapter extends PassthroughAdapter { /** * Parses RDF data found at a Client ID. + * * @param data - Raw data from the Client ID. * @param id - The actual Client ID. * @param response - Response object from the request. diff --git a/src/init/AppRunner.ts b/src/init/AppRunner.ts index 0baca15c3..d3b1ebd77 100644 --- a/src/init/AppRunner.ts +++ b/src/init/AppRunner.ts @@ -203,6 +203,7 @@ export class AppRunner { /** * Retrieves settings from package.json or configuration file when * part of an npm project. + * * @returns The settings defined in the configuration file */ public async getPackageSettings(): Promise> { diff --git a/src/init/ConfigPodInitializer.ts b/src/init/ConfigPodInitializer.ts index 228cefb70..da5573e26 100644 --- a/src/init/ConfigPodInitializer.ts +++ b/src/init/ConfigPodInitializer.ts @@ -14,6 +14,7 @@ import { Initializer } from './Initializer'; * Part of the dynamic pod creation. * Reads the contents from the configuration storage, uses those values to instantiate ResourceStores, * and then adds them to the routing storage. + * * @see {@link ConfigPodManager}, {@link TemplatedPodGenerator}, {@link BaseUrlRouterRule} */ export class ConfigPodInitializer extends Initializer { diff --git a/src/init/cluster/ClusterManager.ts b/src/init/cluster/ClusterManager.ts index caf38828b..1bbfcdeaa 100644 --- a/src/init/cluster/ClusterManager.ts +++ b/src/init/cluster/ClusterManager.ts @@ -18,7 +18,9 @@ enum ClusterMode { /** * Convert workers amount to {@link ClusterMode} + * * @param workers - Amount of workers + * * @returns ClusterMode enum value */ function toClusterMode(workers: number): ClusterMode { @@ -92,6 +94,7 @@ export class ClusterManager { /** * Check whether the CSS server was booted in single threaded mode. + * * @returns True is single threaded. */ public isSingleThreaded(): boolean { @@ -100,6 +103,7 @@ export class ClusterManager { /** * Whether the calling process is the primary process. + * * @returns True if primary */ public isPrimary(): boolean { @@ -108,6 +112,7 @@ export class ClusterManager { /** * Whether the calling process is a worker process. + * * @returns True if worker */ public isWorker(): boolean { diff --git a/src/init/cluster/SingleThreaded.ts b/src/init/cluster/SingleThreaded.ts index 685267c80..591632271 100644 --- a/src/init/cluster/SingleThreaded.ts +++ b/src/init/cluster/SingleThreaded.ts @@ -11,8 +11,10 @@ export interface SingleThreaded {} /** * Convert an exported interface name to the properly expected Components.js type URI. + * * @param componentsManager - The currently used ComponentsManager * @param interfaceName - An interface name + * * @returns A Components.js type URI */ export async function toComponentsJsType(componentsManager: ComponentsManager, interfaceName: string): @@ -38,6 +40,7 @@ Promise { /** * Will list class names of components instantiated implementing the {@link SingleThreaded} * interface while the application is being run in multithreaded mode. + * * @param componentsManager - The componentsManager being used to set up the application */ export async function listSingleThreadedComponents(componentsManager: ComponentsManager): Promise { diff --git a/src/logging/LogUtil.ts b/src/logging/LogUtil.ts index 04628a073..2498b09cd 100644 --- a/src/logging/LogUtil.ts +++ b/src/logging/LogUtil.ts @@ -42,6 +42,7 @@ export function getLoggerFor(loggable: string | Instance): Logger { /** * Sets the global logger factory. * This causes loggers created by {@link getLoggerFor} to delegate to a logger from the given factory. + * * @param loggerFactory - A logger factory. */ export function setGlobalLoggerFactory(loggerFactory: LoggerFactory): void { diff --git a/src/logging/Logger.ts b/src/logging/Logger.ts index 5bcbb81e8..62f69e593 100644 --- a/src/logging/Logger.ts +++ b/src/logging/Logger.ts @@ -17,6 +17,7 @@ export interface SimpleLogger { /** * Log the given message at the given level. * If the internal level is higher than the given level, the message may be voided. + * * @param level - The level to log at. * @param message - The message to log. * @param meta - Optional metadata to include in the log message. @@ -33,6 +34,7 @@ export interface Logger extends SimpleLogger { /** * Log the given message at the given level. * If the internal level is higher than the given level, the message may be voided. + * * @param level - The level to log at. * @param message - The message to log. * @param meta - Optional metadata to include in the log message. @@ -41,6 +43,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'error' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ @@ -48,6 +51,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'warn' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ @@ -55,6 +59,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'info' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ @@ -62,6 +67,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'verbose' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ @@ -69,6 +75,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'debug' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ @@ -76,6 +83,7 @@ export interface Logger extends SimpleLogger { /** * Log a message at the 'silly' level. + * * @param message - The message to log. * @param meta - Optional metadata to include in the log message. */ diff --git a/src/logging/LoggerFactory.ts b/src/logging/LoggerFactory.ts index 4abe886e3..34dd279c1 100644 --- a/src/logging/LoggerFactory.ts +++ b/src/logging/LoggerFactory.ts @@ -6,6 +6,7 @@ import type { Logger } from './Logger'; export interface LoggerFactory { /** * Create a logger instance for the given label. + * * @param label - A label that is used to identify the given logger. */ createLogger: (label: string) => Logger; diff --git a/src/pods/PodManager.ts b/src/pods/PodManager.ts index b696faaeb..1881c2686 100644 --- a/src/pods/PodManager.ts +++ b/src/pods/PodManager.ts @@ -7,6 +7,7 @@ import type { PodSettings } from './settings/PodSettings'; export interface PodManager { /** * Creates a pod for the given settings. + * * @param settings - Settings describing the pod. * @param overwrite - If the creation should proceed if there already is a resource there. */ diff --git a/src/pods/generate/BaseComponentsJsFactory.ts b/src/pods/generate/BaseComponentsJsFactory.ts index d49ac8e88..00ba376d5 100644 --- a/src/pods/generate/BaseComponentsJsFactory.ts +++ b/src/pods/generate/BaseComponentsJsFactory.ts @@ -29,6 +29,7 @@ export class BaseComponentsJsFactory implements ComponentsJsFactory { /** * Calls Components.js to instantiate a new object. + * * @param configPath - Location of the config to instantiate. * @param componentIri - Iri of the object in the config that will be the result. * @param variables - Variables to send to Components.js diff --git a/src/pods/generate/ComponentsJsFactory.ts b/src/pods/generate/ComponentsJsFactory.ts index 6ce82bcc4..978217e8f 100644 --- a/src/pods/generate/ComponentsJsFactory.ts +++ b/src/pods/generate/ComponentsJsFactory.ts @@ -4,6 +4,7 @@ export interface ComponentsJsFactory { /** * Instantiates a new object using Components.js. + * * @param configPath - Location of the config to instantiate. * @param componentIri - Iri of the object in the config that will be the result. * @param variables - Variables to send to Components.js diff --git a/src/pods/generate/GenerateUtil.ts b/src/pods/generate/GenerateUtil.ts index e20cabdec..e1834beb8 100644 --- a/src/pods/generate/GenerateUtil.ts +++ b/src/pods/generate/GenerateUtil.ts @@ -4,6 +4,7 @@ import type { ResourcesGenerator } from './ResourcesGenerator'; /** * Generates resources with the given generator and adds them to the given store. + * * @param settings - Settings from which the pod is being created. * @param generator - Generator to be used. * @param store - Store to be updated. diff --git a/src/pods/generate/ResourcesGenerator.ts b/src/pods/generate/ResourcesGenerator.ts index b8089c16a..492f4ab19 100644 --- a/src/pods/generate/ResourcesGenerator.ts +++ b/src/pods/generate/ResourcesGenerator.ts @@ -15,6 +15,7 @@ export interface ResourcesGenerator { /** * Generates resources with the given options. * The output Iterable should be sorted so that containers always appear before their contents. + * * @param location - Base identifier. * @param options - Options that can be used when generating resources. * diff --git a/src/pods/generate/TemplatedResourcesGenerator.ts b/src/pods/generate/TemplatedResourcesGenerator.ts index f097ba952..840563331 100644 --- a/src/pods/generate/TemplatedResourcesGenerator.ts +++ b/src/pods/generate/TemplatedResourcesGenerator.ts @@ -11,6 +11,7 @@ export interface TemplatedResourcesGenerator { /** * Generates resources with the given options, based on the given template folder. * The output Iterable should be sorted so that containers always appear before their contents. + * * @param templateFolder - Folder where the templates are located. * @param location - Base identifier. * @param options - Options that can be used when generating resources. diff --git a/src/server/middleware/StaticAssetHandler.ts b/src/server/middleware/StaticAssetHandler.ts index 5b6358e27..33b58c8f9 100644 --- a/src/server/middleware/StaticAssetHandler.ts +++ b/src/server/middleware/StaticAssetHandler.ts @@ -39,6 +39,7 @@ export class StaticAssetHandler extends HttpHandler { /** * Creates a handler for the provided static resources. + * * @param assets - A list of {@link StaticAssetEntry}. * @param baseUrl - The base URL of the server. * @param options - Specific options. diff --git a/src/server/notifications/NotificationChannelStorage.ts b/src/server/notifications/NotificationChannelStorage.ts index 796df6be2..ac72514f5 100644 --- a/src/server/notifications/NotificationChannelStorage.ts +++ b/src/server/notifications/NotificationChannelStorage.ts @@ -11,6 +11,7 @@ export interface NotificationChannelStorage { /** * Returns the requested channel. * `undefined` if no match was found or if the notification channel expired. + * * @param id - The identifier of the notification channel. */ get: (id: string) => Promise; @@ -18,12 +19,14 @@ export interface NotificationChannelStorage { /** * Returns the identifiers of all notification channel entries that have the given identifier as their topic. * The identifiers can potentially correspond to expired channels. + * * @param topic - The identifier that is the topic. */ getAll: (topic: ResourceIdentifier) => Promise; /** * Adds the given channel to the storage. + * * @param channel - Channel to add. */ add: (channel: NotificationChannel) => Promise; @@ -31,6 +34,7 @@ export interface NotificationChannelStorage { /** * Updates the given notification channel. * The `id` and the `topic` can not be updated. + * * @param channel - The channel to update. */ update: (channel: NotificationChannel) => Promise; @@ -38,6 +42,7 @@ export interface NotificationChannelStorage { /** * Deletes the given notification channel from the storage. * Returns true if the channel existed. + * * @param id - The identifier of the notification channel */ delete: (id: string) => Promise; diff --git a/src/server/notifications/NotificationChannelType.ts b/src/server/notifications/NotificationChannelType.ts index 53a92e108..54f4fab29 100644 --- a/src/server/notifications/NotificationChannelType.ts +++ b/src/server/notifications/NotificationChannelType.ts @@ -31,6 +31,7 @@ export interface NotificationChannelType { /** * Validate and convert the input quads into a {@link NotificationChannel}. + * * @param data - The input quads. * @param credentials - The credentials of the agent doing the request. */ @@ -38,12 +39,14 @@ export interface NotificationChannelType { /** * Converts a {@link NotificationChannel} to a serialized JSON-LD representation. + * * @param channel - The notification channel to serialize. */ toJsonLd: (channel: NotificationChannel) => Promise>; /** * Determines which modes are required to allow the given notification channel. + * * @param channel - The notification channel to verify. * * @returns The required modes. @@ -53,6 +56,7 @@ export interface NotificationChannelType { /** * This function will be called after the serialized channel is sent back as a response, * allowing for any final actions that need to happen. + * * @param channel - The notification channel that is completed. */ completeChannel: (channel: NotificationChannel) => Promise; diff --git a/src/server/notifications/WebSocketChannel2023/WebSocket2023Util.ts b/src/server/notifications/WebSocketChannel2023/WebSocket2023Util.ts index dd39b802e..4394dc2f8 100644 --- a/src/server/notifications/WebSocketChannel2023/WebSocket2023Util.ts +++ b/src/server/notifications/WebSocketChannel2023/WebSocket2023Util.ts @@ -3,6 +3,7 @@ import { BadRequestHttpError } from '../../../util/errors/BadRequestHttpError'; /** * Generates a WebSocket URL by converting an HTTP(S) URL into a WS(S) URL. + * * @param id - The identifier of the channel. Needs to be a URL. */ export function generateWebSocketUrl(id: string): string { diff --git a/src/server/util/RedirectingHttpHandler.ts b/src/server/util/RedirectingHttpHandler.ts index 2cf766dd5..44e8d6071 100644 --- a/src/server/util/RedirectingHttpHandler.ts +++ b/src/server/util/RedirectingHttpHandler.ts @@ -37,6 +37,7 @@ export class RedirectingHttpHandler extends HttpHandler { /** * Creates a handler for the provided redirects. + * * @param redirects - A mapping between URL patterns. * @param baseUrl - Base URL of the server. * @param targetExtractor - To extract the target from the request. diff --git a/src/storage/DataAccessorBasedStore.ts b/src/storage/DataAccessorBasedStore.ts index 28b71d7e2..d0d232122 100644 --- a/src/storage/DataAccessorBasedStore.ts +++ b/src/storage/DataAccessorBasedStore.ts @@ -376,6 +376,7 @@ export class DataAccessorBasedStore implements ResourceStore { * * First the identifier gets requested and if no result is found * the identifier with differing trailing slash is requested. + * * @param identifier - Identifier that needs to be checked. */ protected async getNormalizedMetadata(identifier: ResourceIdentifier): Promise { @@ -411,6 +412,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Write the given metadata resource to the DataAccessor. + * * @param identifier - Identifier of the metadata. * @param representation - Corresponding Representation. * @@ -451,6 +453,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Write the given resource to the DataAccessor. Metadata will be updated with necessary triples. * In case of containers `handleContainerData` will be used to verify the data. + * * @param identifier - Identifier of the resource. * @param representation - Corresponding Representation. * @param isContainer - Is the incoming resource a container? @@ -576,6 +579,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Validates if the slug and headers are valid. * Errors if slug exists, ends on slash, but ContainerType Link header is NOT present + * * @param isContainer - Is the slug supposed to represent a container? * @param slug - Is the requested slug (if any). */ @@ -588,6 +592,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Clean http Slug to be compatible with the server. Makes sure there are no unwanted characters * e.g.: cleanslug('&%26') returns '%26%26' + * * @param slug - the slug to clean */ protected cleanSlug(slug: string): string { @@ -633,6 +638,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Checks if the given metadata represents a (potential) container, * based on the metadata. + * * @param metadata - Metadata of the (new) resource. */ protected isContainerType(metadata: RepresentationMetadata): boolean { @@ -687,6 +693,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Create containers starting from the root until the given identifier corresponds to an existing container. * Will throw errors if the identifier of the last existing "container" corresponds to an existing document. + * * @param container - Identifier of the container which will need to exist. */ protected async createRecursiveContainers(container: ResourceIdentifier): Promise { @@ -719,6 +726,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Generates activity metadata for a resource and adds it to the {@link ChangeMap} + * * @param map - ChangeMap to update. * @param id - Identifier of the resource being changed. * @param activity - Which activity is taking place. @@ -729,6 +737,7 @@ export class DataAccessorBasedStore implements ResourceStore { /** * Generates activity metadata specifically for Add/Remove events on a container. + * * @param map - ChangeMap to update. * @param id - Identifier of the container. * @param add - If there is a resource being added (`true`) or removed (`false`). diff --git a/src/storage/ResourceSet.ts b/src/storage/ResourceSet.ts index 05b8fec73..c093000bc 100644 --- a/src/storage/ResourceSet.ts +++ b/src/storage/ResourceSet.ts @@ -6,6 +6,7 @@ import type { ResourceIdentifier } from '../http/representation/ResourceIdentifi export interface ResourceSet { /** * Check if a resource exists in this ResourceSet. + * * @param identifier - Identifier of resource to check. * * @returns A promise resolving if the resource already exists. diff --git a/src/storage/ResourceStore.ts b/src/storage/ResourceStore.ts index 7f3d00e4d..141b5f93d 100644 --- a/src/storage/ResourceStore.ts +++ b/src/storage/ResourceStore.ts @@ -28,6 +28,7 @@ export type ChangeMap = IdentifierMap; export interface ResourceStore extends ResourceSet { /** * Retrieves a representation of a resource. + * * @param identifier - Identifier of the resource to read. * @param preferences - Preferences indicating desired representations. * @param conditions - Optional conditions under which to proceed. @@ -43,6 +44,7 @@ export interface ResourceStore extends ResourceSet { /** * Sets or replaces the representation of a resource, * creating a new resource and intermediary containers as needed. + * * @param identifier - Identifier of resource to update. * @param representation - New representation of the resource. * @param conditions - Optional conditions under which to proceed. @@ -57,6 +59,7 @@ export interface ResourceStore extends ResourceSet { /** * Creates a new resource in the container. + * * @param container - Container in which to create a resource. * @param representation - Representation of the new resource * @param conditions - Optional conditions under which to proceed. @@ -71,6 +74,7 @@ export interface ResourceStore extends ResourceSet { /** * Deletes a resource. + * * @param identifier - Identifier of resource to delete. * @param conditions - Optional conditions under which to proceed. * @@ -84,6 +88,7 @@ export interface ResourceStore extends ResourceSet { /** * Sets or updates the representation of a resource, * creating a new resource and intermediary containers as needed. + * * @param identifier - Identifier of resource to update. * @param patch - Description of which parts to update. * @param conditions - Optional conditions under which to proceed. diff --git a/src/storage/accessors/DataAccessor.ts b/src/storage/accessors/DataAccessor.ts index 59e3636fb..6037df74b 100644 --- a/src/storage/accessors/DataAccessor.ts +++ b/src/storage/accessors/DataAccessor.ts @@ -16,6 +16,7 @@ import type { Guarded } from '../../util/GuardedStream'; export interface DataAccessor { /** * Should throw a NotImplementedHttpError if the DataAccessor does not support storing the given Representation. + * * @param representation - Incoming Representation. * * @throws BadRequestHttpError @@ -26,6 +27,7 @@ export interface DataAccessor { /** * Returns a data stream stored for the given identifier. * It can be assumed that the incoming identifier will always correspond to a document. + * * @param identifier - Identifier for which the data is requested. */ getData: (identifier: ResourceIdentifier) => Promise>; @@ -56,6 +58,7 @@ export interface DataAccessor { /** * Writes data and metadata for a document. * If any data and/or metadata exist for the given identifier, it should be overwritten. + * * @param identifier - Identifier of the resource. * @param data - Data to store. * @param metadata - Metadata to store. @@ -67,6 +70,7 @@ export interface DataAccessor { * Writes metadata for a container. * If the container does not exist yet it should be created, * if it does its metadata should be overwritten, except for the containment triples. + * * @param identifier - Identifier of the container. * @param metadata - Metadata to store. */ @@ -75,6 +79,7 @@ export interface DataAccessor { /** * Writes metadata for a resource. * It can safely be assumed that the subject resource already exists. + * * @param identifier - Identifier of the subject resource. * @param metadata - Metadata to store. */ diff --git a/src/storage/accessors/FileDataAccessor.ts b/src/storage/accessors/FileDataAccessor.ts index 4545689df..d409004b8 100644 --- a/src/storage/accessors/FileDataAccessor.ts +++ b/src/storage/accessors/FileDataAccessor.ts @@ -139,6 +139,7 @@ export class FileDataAccessor implements DataAccessor { /** * Gets the Stats object corresponding to the given file path, * resolving symbolic links. + * * @param path - File path to get info from. * * @throws NotFoundHttpError @@ -188,6 +189,7 @@ export class FileDataAccessor implements DataAccessor { /** * Writes the metadata of the resource to a meta file. + * * @param link - Path related metadata of the resource. * @param metadata - Metadata to write. * @@ -226,6 +228,7 @@ export class FileDataAccessor implements DataAccessor { /** * Generates metadata relevant for any resources stored by this accessor. + * * @param link - Path related metadata. * @param stats - Stats objects of the corresponding directory. * @param isContainer - If the path points to a container (directory) or not. @@ -319,6 +322,7 @@ export class FileDataAccessor implements DataAccessor { /** * Helper function to add file system related metadata. + * * @param metadata - metadata object to add to * @param stats - Stats of the file/directory corresponding to the resource. */ @@ -351,6 +355,7 @@ export class FileDataAccessor implements DataAccessor { /** * Helper function without extra validation checking to create a data file. + * * @param path - The filepath of the file to be created. * @param data - The data to be put in the file. */ diff --git a/src/storage/accessors/SparqlDataAccessor.ts b/src/storage/accessors/SparqlDataAccessor.ts index 485725df7..9efdb910f 100644 --- a/src/storage/accessors/SparqlDataAccessor.ts +++ b/src/storage/accessors/SparqlDataAccessor.ts @@ -174,6 +174,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Creates the name for the metadata of a resource. + * * @param name - Name of the (non-metadata) resource. */ private getMetadataNode(name: NamedNode): NamedNode { @@ -189,6 +190,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Creates a CONSTRUCT query that returns all quads contained within a single resource. + * * @param name - Name of the resource to query. */ private sparqlConstruct(name: NamedNode): ConstructQuery { @@ -213,6 +215,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Creates an update query that overwrites the data and metadata of a resource. * If there are no triples we assume it's a container (so don't overwrite the main graph with containment triples). + * * @param name - Name of the resource to update. * @param metadata - New metadata of the resource. * @param parent - Name of the parent to update the containment triples. @@ -255,6 +258,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Creates an update query that overwrites metadata of a resource. + * * @param metaName - Name of the metadata resource to update. * @param metadata - New metadata of the resource. */ @@ -280,6 +284,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Creates a query that deletes everything related to the given name. + * * @param name - Name of resource to delete. * @param parent - Parent of the resource to delete so the containment triple can be removed (unless root). */ @@ -306,6 +311,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Helper function for creating SPARQL update queries. * Creates an operation for deleting all triples in a graph. + * * @param name - Name of the graph to delete. */ private sparqlUpdateDeleteAll(name: NamedNode): InsertDeleteOperation { @@ -318,6 +324,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Helper function for creating SPARQL update queries. * Creates a Graph selector with the given triples. + * * @param name - Name of the graph. * @param triples - Triples/triple patterns to select. */ @@ -327,6 +334,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Sends a SPARQL CONSTRUCT query to the endpoint and returns a stream of quads. + * * @param sparqlQuery - Query to execute. */ private async sendSparqlConstruct(sparqlQuery: ConstructQuery): Promise> { @@ -342,6 +350,7 @@ export class SparqlDataAccessor implements DataAccessor { /** * Sends a SPARQL update query to the stored endpoint. + * * @param sparqlQuery - Query to send. */ private async sendSparqlUpdate(sparqlQuery: Update): Promise { diff --git a/src/storage/conditions/Conditions.ts b/src/storage/conditions/Conditions.ts index 067eaccb7..e87b8f378 100644 --- a/src/storage/conditions/Conditions.ts +++ b/src/storage/conditions/Conditions.ts @@ -23,6 +23,7 @@ export interface Conditions { /** * Checks validity based on the given metadata. + * * @param metadata - Metadata of the representation. Undefined if the resource does not exist. * @param strict - How to compare the ETag related headers. * If true, the comparison will happen on representation level. diff --git a/src/storage/conditions/ETagHandler.ts b/src/storage/conditions/ETagHandler.ts index c4c26ddf0..1420e8f38 100644 --- a/src/storage/conditions/ETagHandler.ts +++ b/src/storage/conditions/ETagHandler.ts @@ -26,6 +26,7 @@ export interface ETagHandler { /** * Validates whether 2 ETags correspond to the same state of a resource, * independent of the representation the ETags correspond to. + * * @param eTag1 - First ETag to compare. * @param eTag2 - Second ETag to compare. */ diff --git a/src/storage/conversion/ConversionUtil.ts b/src/storage/conversion/ConversionUtil.ts index 3b7dc6fae..8d5eba862 100644 --- a/src/storage/conversion/ConversionUtil.ts +++ b/src/storage/conversion/ConversionUtil.ts @@ -164,6 +164,7 @@ export function matchesMediaPreferences(type: string, preferred?: ValuePreferenc /** * Checks if the given two media types/ranges match each other. * Takes wildcards into account. + * * @param mediaA - Media type to match. * @param mediaB - Media type to match. * @@ -202,6 +203,7 @@ export function isInternalContentType(contentType?: string): boolean { /** * Serializes a preferences object to a string for display purposes. + * * @param preferences - Preferences to serialize */ export function preferencesToString(preferences: ValuePreferences): string { diff --git a/src/storage/keyvalue/JsonFileStorage.ts b/src/storage/keyvalue/JsonFileStorage.ts index 063591bd3..1be62d51b 100644 --- a/src/storage/keyvalue/JsonFileStorage.ts +++ b/src/storage/keyvalue/JsonFileStorage.ts @@ -61,6 +61,7 @@ export class JsonFileStorage implements KeyValueStorage { /** * Updates the data in the JSON file while using a write lock. + * * @param updateFn - A function that updates the JSON object. * * @returns The return value of `updateFn`. diff --git a/src/storage/keyvalue/KeyValueStorage.ts b/src/storage/keyvalue/KeyValueStorage.ts index 4b238274f..e98889865 100644 --- a/src/storage/keyvalue/KeyValueStorage.ts +++ b/src/storage/keyvalue/KeyValueStorage.ts @@ -6,18 +6,21 @@ export interface KeyValueStorage { /** * Returns the value stored for the given identifier. * `undefined` if no value is stored. + * * @param identifier - Identifier to get the value for. */ get: (key: TKey) => Promise; /** * Checks if there is a value stored for the given key. + * * @param identifier - Identifier to check. */ has: (key: TKey) => Promise; /** * Sets the value for the given key. + * * @param key - Key to set/update. * @param value - Value to store. * @@ -27,6 +30,7 @@ export interface KeyValueStorage { /** * Deletes the value stored for the given key. + * * @param key - Key to delete. * * @returns If there was a value to delete. diff --git a/src/storage/mapping/BaseFileIdentifierMapper.ts b/src/storage/mapping/BaseFileIdentifierMapper.ts index a5440afec..c4c0540c9 100644 --- a/src/storage/mapping/BaseFileIdentifierMapper.ts +++ b/src/storage/mapping/BaseFileIdentifierMapper.ts @@ -36,6 +36,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { * Maps the given resource identifier / URL to a file path. * Determines the content type if none was provided. * For containers the content-type input is ignored. + * * @param identifier - The input identifier. * @param isMetadata - If we need the data or metadata file path. * @param contentType - The content-type provided with the request. @@ -59,6 +60,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Maps the given container identifier to a file path, * possibly making alterations to the direct translation. + * * @param identifier - The input identifier. * @param filePath - The direct translation of the identifier onto the file path. * @@ -74,6 +76,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { * possibly making alterations to the direct translation * (for instance, based on its content type)). * Determines the content type if none was provided. + * * @param identifier - The input identifier. * @param filePath - The direct translation of the identifier onto the file path. * @param contentType - The content-type provided with the request. @@ -92,6 +95,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Determines the content type from the document identifier. + * * @param identifier - The input identifier. * @param contentType - The content-type provided with the request. * @@ -103,6 +107,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Maps the given file path to a URL and determines its content type. + * * @param filePath - The input file path. * @param isContainer - If the path corresponds to a file. * @@ -134,6 +139,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Maps the given container path to a URL and determines its content type. + * * @param relative - The relative container path. * * @returns A ResourceLink with all the necessary metadata. @@ -144,6 +150,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Maps the given document path to a URL and determines its content type. + * * @param relative - The relative document path. * * @returns A ResourceLink with all the necessary metadata. @@ -154,6 +161,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Determines the content type from the relative path. + * * @param filePath - The file path of the document. * * @returns The content type of the document. @@ -165,6 +173,7 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Get the absolute file path based on the rootFilepath. + * * @param path - The relative file path. * * @returns Absolute path of the file. @@ -175,12 +184,13 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Strips the baseRequestURI from the identifier. + * * @param identifier - Incoming identifier. * + * @returns A string representing the relative path. + * * @throws NotFoundHttpError * If the identifier does not match the baseRequestURI. - * - * @returns A string representing the relative path. */ protected getRelativePath(identifier: ResourceIdentifier): string { if (!identifier.path.startsWith(this.baseRequestURI)) { @@ -193,11 +203,11 @@ export class BaseFileIdentifierMapper implements FileIdentifierMapper { /** * Check if the given relative path is valid. * - * @throws BadRequestHttpError - * If the relative path is invalid. - * * @param path - A relative path, as generated by {@link getRelativePath}. * @param identifier - A resource identifier. + * + * @throws BadRequestHttpError + * If the relative path is invalid. */ protected validateRelativePath(path: string, identifier: ResourceIdentifier): void { if (!path.startsWith('/')) { diff --git a/src/storage/mapping/FileIdentifierMapper.ts b/src/storage/mapping/FileIdentifierMapper.ts index f56fad618..4c4bf1556 100644 --- a/src/storage/mapping/FileIdentifierMapper.ts +++ b/src/storage/mapping/FileIdentifierMapper.ts @@ -25,6 +25,7 @@ export interface ResourceLink { export interface FileIdentifierMapper { /** * Maps the given file path to an URL and determines the content-type + * * @param filePath - The input file path. * @param isContainer - If the path corresponds to a file. * @@ -36,6 +37,7 @@ export interface FileIdentifierMapper { * Determines the content-type if no content-type was provided by finding the corresponding file. * If there is no corresponding file a file path will be generated. * For containers the content-type input gets ignored. + * * @param identifier - The input identifier. * @param isMetadata - If we are mapping the metadata of the resource instead of its data. * @param contentType - The (optional) content-type of the resource. diff --git a/src/storage/quota/QuotaStrategy.ts b/src/storage/quota/QuotaStrategy.ts index 07efd6095..07324f2f1 100644 --- a/src/storage/quota/QuotaStrategy.ts +++ b/src/storage/quota/QuotaStrategy.ts @@ -33,6 +33,7 @@ export abstract class QuotaStrategy { * as available space. * * @param identifier - the identifier of the resource of which you want the available space + * * @returns the available space and the unit of the space as a Size object */ public async getAvailableSpace(identifier: ResourceIdentifier): Promise { @@ -57,6 +58,7 @@ export abstract class QuotaStrategy { * Get the currently used/occupied space. * * @param identifier - the identifier that should be used to calculate the total + * * @returns a Size object containing the requested value. * If quota is not relevant for this identifier, Size.amount should be Number.MAX_SAFE_INTEGER */ @@ -66,6 +68,7 @@ export abstract class QuotaStrategy { * Get an estimated size of the resource * * @param metadata - the metadata that might include the size + * * @returns a Size object containing the estimated size and unit of the resource */ public async estimateSize(metadata: RepresentationMetadata): Promise { @@ -79,6 +82,7 @@ export abstract class QuotaStrategy { * Like other Passthrough instances this will simply pass on the chunks, when the quota isn't exceeded. * * @param identifier - the identifier of the resource in question + * * @returns a Passthrough instance that errors when quota is exceeded */ public async createQuotaGuard(identifier: ResourceIdentifier): Promise> { diff --git a/src/storage/routing/BaseUrlRouterRule.ts b/src/storage/routing/BaseUrlRouterRule.ts index fd59ba515..11fe9d12d 100644 --- a/src/storage/routing/BaseUrlRouterRule.ts +++ b/src/storage/routing/BaseUrlRouterRule.ts @@ -11,6 +11,7 @@ import { RouterRule } from './RouterRule'; * * Part of the dynamic pod creation. * Uses the identifiers that were added to the routing storage. + * * @see {@link TemplatedPodGenerator}, {@link ConfigPodInitializer}, {@link ConfigPodManager} */ export class BaseUrlRouterRule extends RouterRule { diff --git a/src/storage/size-reporter/FileSizeReporter.ts b/src/storage/size-reporter/FileSizeReporter.ts index 78f120f28..d26ce8363 100644 --- a/src/storage/size-reporter/FileSizeReporter.ts +++ b/src/storage/size-reporter/FileSizeReporter.ts @@ -49,6 +49,7 @@ export class FileSizeReporter implements SizeReporter { * Get the total size of a resource and its children if present * * @param fileLocation - the resource of which you want the total size of ( on disk ) + * * @returns a number specifying how many bytes are used by the resource */ private async getTotalSize(fileLocation: string): Promise { diff --git a/src/storage/size-reporter/SizeReporter.ts b/src/storage/size-reporter/SizeReporter.ts index 30ec5d59b..d18b91a45 100644 --- a/src/storage/size-reporter/SizeReporter.ts +++ b/src/storage/size-reporter/SizeReporter.ts @@ -20,6 +20,7 @@ export interface SizeReporter { * Get the size of a given resource * * @param identifier - the resource of which you want the size + * * @returns The size of the resource as a Size object calculated recursively * if the identifier leads to a container */ @@ -29,6 +30,7 @@ export interface SizeReporter { * Calculate the size of a chunk based on which SizeReporter is being used * * @param chunk - the chunk of which you want the size + * * @returns the size of the passed chunk as a number */ calculateChunkSize: (chunk: T) => Promise; @@ -37,6 +39,7 @@ export interface SizeReporter { * Estimate the size of a body / request by looking at its metadata * * @param metadata - the metadata of the resource you want an estimated size of + * * @returns the estimated size of the body / request or undefined if no * meaningful estimation can be made */ diff --git a/src/util/Header.ts b/src/util/Header.ts index 06f43b259..dd5102633 100644 --- a/src/util/Header.ts +++ b/src/util/Header.ts @@ -55,6 +55,7 @@ export class ContentType { /** * Serialize this ContentType object to a ContentType header appropriate value string. + * * @returns The value string, including parameters, if present. */ public toHeaderValueString(): string { diff --git a/src/util/HeaderUtil.ts b/src/util/HeaderUtil.ts index 5c9ea8ffd..00cf20f84 100644 --- a/src/util/HeaderUtil.ts +++ b/src/util/HeaderUtil.ts @@ -29,12 +29,13 @@ const logger = getLoggerFor('HeaderUtil'); // HELPER FUNCTIONS /** * Replaces all double quoted strings in the input string with `"0"`, `"1"`, etc. + * * @param input - The Accept header string. * + * @returns The transformed string and a map with keys `"0"`, etc. and values the original string that was there. + * * @throws BadRequestHttpError * Thrown if invalid characters are detected in a quoted string. - * - * @returns The transformed string and a map with keys `"0"`, etc. and values the original string that was there. */ export function transformQuotedStrings(input: string): { result: string; replacements: Record } { let idx = 0; @@ -200,6 +201,7 @@ function parseAcceptPart(part: string, replacements: Record, str /** * Parses an Accept-* header where each part is only a value and a weight, so roughly /.*(q=.*)?/ separated by commas. * The returned weights default to 1 if no q value is found or the q value is invalid. + * * @param input - Input header string. * @param strict - Determines if invalid values throw errors (`true`) or log warnings (`false`). Defaults to `false`. * @@ -371,10 +373,10 @@ export function addHeader(response: HttpResponse, name: string, value: string | * * @param input - The Content-Type header string. * + * @returns A {@link ContentType} object containing the value and optional parameters. + * * @throws BadRequestHttpError * Thrown on invalid header syntax. - * - * @returns A {@link ContentType} object containing the value and optional parameters. */ export function parseContentType(input: string): ContentType { // Quoted strings could prevent split from having correct results @@ -438,6 +440,7 @@ export function parseForwarded(headers: IncomingHttpHeaders): Forwarded { * Parses the link header(s) and returns an array of LinkEntry objects. * * @param link - A single link header or an array of link headers + * * @returns A LinkEntry array, LinkEntry contains a link and a params Record<string,string> */ export function parseLinkHeader(link: string | string[] = []): LinkEntry[] { @@ -484,6 +487,7 @@ const authSchemeRegexCache: Map = new Map(); * * @param scheme - Name of the authorization scheme (case insensitive). * @param authorization - The value of the Authorization header (may be undefined). + * * @returns True if the Authorization header uses the specified scheme, false otherwise. */ export function matchesAuthorizationScheme(scheme: string, authorization?: string): boolean { @@ -500,6 +504,7 @@ export function matchesAuthorizationScheme(scheme: string, authorization?: strin * * @param url - A string representing the URL. * @param schemes - Scheme value options (the function will check if at least one matches the URL scheme). + * * @returns True if the URL scheme matches at least one of the provided options, false otherwise. */ export function hasScheme(url: string, ...schemes: string[]): boolean { diff --git a/src/util/IterableUtil.ts b/src/util/IterableUtil.ts index 79a57ebeb..81a0d7bfc 100644 --- a/src/util/IterableUtil.ts +++ b/src/util/IterableUtil.ts @@ -48,6 +48,7 @@ export function* filter( /** * Creates a new iterable that is a concatenation of all the iterables in the input. + * * @param iterables - An iterable of which the contents will be concatenated into a new iterable. */ export function* concat(iterables: Iterable>): Iterable { diff --git a/src/util/LockUtils.ts b/src/util/LockUtils.ts index 5df47f554..d363ff245 100644 --- a/src/util/LockUtils.ts +++ b/src/util/LockUtils.ts @@ -5,8 +5,10 @@ const logger = getLoggerFor('LockUtil'); /** * Waits a set amount of time, without consuming cpu, with a set amount of jitter. + * * @param delay - How long to wait. * @param jitter - A fraction of this jitter will be added to the delay. + * * @returns A promise that resolves after the specified amount of time. */ export async function setJitterTimeout(delay: number, jitter = 0): Promise { @@ -28,8 +30,8 @@ export interface AttemptSettings { * Will execute the given function until one of the following cases occurs: * * The function resolves to a value: the value is returned. * * The function errors: the rejected error is thrown. - * * The function did not resolve after the set amount of retries: - * the rejected error is returned. + * * The function did not resolve after the set amount of retries: the rejected error is returned. + * * @param fn - The function to retry. **This function must return a value!** * @param settings - The options on how to retry the function */ diff --git a/src/util/PathUtil.ts b/src/util/PathUtil.ts index c9c9e6de1..d6ede69b9 100644 --- a/src/util/PathUtil.ts +++ b/src/util/PathUtil.ts @@ -113,6 +113,7 @@ export function trimLeadingSlashes(path: string): string { /** * Extracts the extension (without dot) from a path. * Custom function since `path.extname` does not work on all cases (e.g. ".acl") + * * @param path - Input path to parse. */ export function getExtension(path: string): string { @@ -150,6 +151,7 @@ function transformPathComponents(path: string, transform: (part: string) => stri * the provided path. * * @param path - The path to convert to its canonical URI path form. + * * @returns The canonical URI path form of the provided path. */ export function toCanonicalUriPath(path: string): string { @@ -178,6 +180,7 @@ const forbiddenRegex = new RegExp(`[${Object.keys(forbiddenSymbols).join('')}]`, * Characters that would result in an illegal file path remain percent encoded. * * @param path - The path to decode the URI path components of. + * * @returns A decoded copy of the provided URI path (ignoring encoded slash characters). */ export function decodeUriPathComponents(path: string): string { @@ -192,6 +195,7 @@ export function decodeUriPathComponents(path: string): string { * lead to unnecessary double encoding, resulting in a URI that differs from the expected result. * * @param path - The path to encode the URI path components of. + * * @returns An encoded copy of the provided URI path (ignoring encoded slash characters). */ export function encodeUriPathComponents(path: string): string { @@ -200,6 +204,7 @@ export function encodeUriPathComponents(path: string): string { /** * Checks if the path corresponds to a container path (ending in a /). + * * @param path - Path to check. */ export function isContainerPath(path: string): boolean { @@ -210,6 +215,7 @@ export function isContainerPath(path: string): boolean { /** * Checks if the identifier corresponds to a container identifier. + * * @param identifier - Identifier to check. */ export function isContainerIdentifier(identifier: ResourceIdentifier): boolean { @@ -219,6 +225,7 @@ export function isContainerIdentifier(identifier: ResourceIdentifier): boolean { /** * Splits a URL (or similar) string into a part containing its scheme and one containing the rest. * E.g., `http://test.com/` results in `{ scheme: 'http://', rest: 'test.com/' }`. + * * @param url - String to parse. */ export function extractScheme(url: string): { scheme: string; rest: string } { @@ -229,6 +236,7 @@ export function extractScheme(url: string): { scheme: string; rest: string } { /** * Creates a relative URL by removing the base URL. * Will throw an error in case the resulting target is not withing the base URL scope. + * * @param baseUrl - Base URL. * @param request - Incoming request of which the target needs to be extracted. * @param targetExtractor - Will extract the target from the request. @@ -251,11 +259,12 @@ Promise { * In case there is a subdomain, the first match of the regular expression will be that subdomain. * * Examples with baseUrl `http://test.com/foo/`: - * - Will match `http://test.com/foo/` - * - Will match `http://test.com/foo/bar/baz` - * - Will match `http://alice.bob.test.com/foo/bar/baz`, first match result will be `alice.bob` - * - Will not match `http://test.com/` - * - Will not match `http://alicetest.com/foo/` + * - Will match `http://test.com/foo/` + * - Will match `http://test.com/foo/bar/baz` + * - Will match `http://alice.bob.test.com/foo/bar/baz`, first match result will be `alice.bob` + * - Will not match `http://test.com/` + * - Will not match `http://alicetest.com/foo/` + * * @param baseUrl - Base URL for the regular expression. */ export function createSubdomainRegexp(baseUrl: string): RegExp { diff --git a/src/util/PromiseUtil.ts b/src/util/PromiseUtil.ts index 690123cc6..e44bd78a5 100644 --- a/src/util/PromiseUtil.ts +++ b/src/util/PromiseUtil.ts @@ -5,6 +5,7 @@ export type PromiseOrValue = T | Promise; /** * Verifies if the given value is a Promise or not. + * * @param object - Object to check. */ export function isPromise(object: PromiseOrValue): object is Promise { diff --git a/src/util/QuadUtil.ts b/src/util/QuadUtil.ts index 494bbfdbc..19e2130ba 100644 --- a/src/util/QuadUtil.ts +++ b/src/util/QuadUtil.ts @@ -9,6 +9,7 @@ import { toNamedTerm } from './TermUtil'; /** * Helper function for serializing an array of quads, with as result a Readable object. + * * @param quads - The array of quads. * @param contentType - The content-type to serialize to. * @@ -20,6 +21,7 @@ export function serializeQuads(quads: Quad[], contentType?: string): Guarded, options: ParserOpt /** * Filter out duplicate quads from an array. + * * @param quads - Quads to filter. * * @returns A new array containing the unique quads. diff --git a/src/util/ResourceUtil.ts b/src/util/ResourceUtil.ts index 72d6f09fa..925c5c8f3 100644 --- a/src/util/ResourceUtil.ts +++ b/src/util/ResourceUtil.ts @@ -13,6 +13,7 @@ import namedNode = DataFactory.namedNode; /** * Helper function to generate type quads for a Container or Resource. + * * @param metadata - Metadata to add to. * @param isContainer - If the identifier corresponds to a container. */ @@ -26,6 +27,7 @@ export function addResourceMetadata(metadata: RepresentationMetadata, isContaine /** * Updates the dc:modified time to the given time. + * * @param metadata - Metadata to update. * @param date - Last modified date. Defaults to current time. */ @@ -38,6 +40,7 @@ export function updateModifiedDate(metadata: RepresentationMetadata, date = new /** * Links a template file with a given content-type to the metadata using the SOLID_META.template predicate. + * * @param metadata - Metadata to update. * @param templateFile - Path to the template. * @param contentType - Content-type of the template after it is rendered. @@ -52,6 +55,7 @@ void { /** * Helper function to clone a representation, the original representation can still be used. * This function loads the entire stream in memory. + * * @param representation - The representation to clone. * * @returns The cloned representation. diff --git a/src/util/StreamUtil.ts b/src/util/StreamUtil.ts index 03524ff0c..3bfa47aab 100644 --- a/src/util/StreamUtil.ts +++ b/src/util/StreamUtil.ts @@ -19,6 +19,7 @@ const logger = getLoggerFor('StreamUtil'); /** * Joins all strings of a stream. + * * @param stream - Stream of strings. * * @returns The joined string. @@ -29,6 +30,7 @@ export async function readableToString(stream: Readable): Promise { /** * Imports quads from a stream into a Store. + * * @param stream - Stream of quads. * * @returns A Store containing all the quads. @@ -42,6 +44,7 @@ export async function readableToQuads(stream: Readable): Promise { /** * Interprets the stream as JSON and converts it to a Dict. + * * @param stream - Stream of JSON data. * * @returns The parsed object. @@ -55,6 +58,7 @@ export async function readJsonStream(stream: Readable): Promise { * Converts the stream to a single object. * This assumes the stream is in object mode and only contains a single element, * otherwise an error will be thrown. + * * @param stream - Object stream with single entry. */ export async function getSingleItem(stream: Readable): Promise { @@ -78,6 +82,7 @@ const safeErrors = new Set([ * Pipes one stream into another and emits errors of the first stream with the second. * In case of an error in the first stream the second one will be destroyed with the given error. * This will also make the stream {@link Guarded}. + * * @param readable - Initial readable stream. * @param destination - The destination for writing data. * @param mapError - Optional function that takes the error and converts it to a new error. @@ -134,6 +139,7 @@ export interface AsyncTransformOptions extends DuplexOptions { /** * Transforms a stream, ensuring that all errors are forwarded. + * * @param source - The stream to be transformed. * @param options - The transformation options. * @param options.transform - The transform function to use. @@ -177,6 +183,7 @@ export function transformSafely( /** * Converts a string or array to a stream and applies an error guard so that it is {@link Guarded}. + * * @param contents - Data to stream. * @param options - Options to pass to the Readable constructor. See {@link Readable.from}. */ diff --git a/src/util/StringUtil.ts b/src/util/StringUtil.ts index 484ee7cd1..fdfcaab52 100644 --- a/src/util/StringUtil.ts +++ b/src/util/StringUtil.ts @@ -13,6 +13,7 @@ export function splitCommaSeparated(input: string): string[] { * Sanitizes part of a URL by replacing non-word content with a '-'. * * @param urlPart - The URL part to sanitize. + * * @returns The sanitized output. */ export function sanitizeUrlPart(urlPart: string): string { @@ -23,6 +24,7 @@ export function sanitizeUrlPart(urlPart: string): string { * Checks the validity of a file name. A valid name consists of word characters, '-' or '.'. * * @param name - The name of the file to validate. + * * @returns True if the filename is valid, false otherwise. */ export function isValidFileName(name: string): boolean { @@ -33,6 +35,7 @@ export function isValidFileName(name: string): boolean { * Checks if the given string is a valid URL. * * @param url - String to check. + * * @returns True if the string is a valid URL. */ export function isUrl(url: string): boolean { @@ -49,6 +52,7 @@ export function isUrl(url: string): boolean { * Converts milliseconds to an ISO 8601 duration string. * The only categories used are days, hours, minutes, and seconds, * because months have no fixed size in milliseconds. + * * @param ms - The duration in ms to convert. */ export function msToDuration(ms: number): string { diff --git a/src/util/TermUtil.ts b/src/util/TermUtil.ts index 14474cf32..caed50f45 100644 --- a/src/util/TermUtil.ts +++ b/src/util/TermUtil.ts @@ -12,6 +12,7 @@ export function isTerm(input?: unknown): input is Term { /** * Converts a string to a named node when needed. + * * @param subject - Subject to potentially transform. */ export function toNamedTerm(subject: string): NamedNode; @@ -25,6 +26,7 @@ export const toPredicateTerm = toNamedTerm; /** * Converts an object term when needed. + * * @param object - Object to potentially transform. * @param preferLiteral - Whether strings are converted to literals or named nodes. */ @@ -40,6 +42,7 @@ export function toObjectTerm(object: Term | string, preferLiteral = false): Term /** * Creates a literal by first converting the dataType string to a named node. + * * @param object - Object value. * @param dataType - Object data type (as string). */ diff --git a/src/util/Vocabularies.ts b/src/util/Vocabularies.ts index 594f5b558..4ab5b2737 100644 --- a/src/util/Vocabularies.ts +++ b/src/util/Vocabularies.ts @@ -88,6 +88,7 @@ string extends TLocal ? PartialVocabulary : Vocabulary { /** * Creates a new {@link Vocabulary} that extends an existing one by adding new local names. + * * @param vocabulary - The {@link Vocabulary} to extend. * @param newNames - The new local names that need to be added. */ diff --git a/src/util/errors/BadRequestHttpError.ts b/src/util/errors/BadRequestHttpError.ts index 87c330fe8..ac982897e 100644 --- a/src/util/errors/BadRequestHttpError.ts +++ b/src/util/errors/BadRequestHttpError.ts @@ -11,6 +11,7 @@ const BaseHttpError = generateHttpErrorClass(400, 'BadRequestHttpError'); export class BadRequestHttpError extends BaseHttpError { /** * Default message is 'The given input is not supported by the server configuration.'. + * * @param message - Optional, more specific, message. * @param options - Optional error options. */ diff --git a/src/util/errors/HttpError.ts b/src/util/errors/HttpError.ts index ed039c105..8a6a42b55 100644 --- a/src/util/errors/HttpError.ts +++ b/src/util/errors/HttpError.ts @@ -29,6 +29,7 @@ export class HttpError extends Error implements HttpE /** * Creates a new HTTP error. Subclasses should call this with their fixed status code. + * * @param statusCode - HTTP status code needed for the HTTP response. * @param name - Error name. Useful for logging and stack tracing. * @param message - Error message. diff --git a/src/util/errors/PayloadHttpError.ts b/src/util/errors/PayloadHttpError.ts index 865f484e6..87f473060 100644 --- a/src/util/errors/PayloadHttpError.ts +++ b/src/util/errors/PayloadHttpError.ts @@ -10,6 +10,7 @@ const BaseHttpError = generateHttpErrorClass(413, 'PayloadHttpError'); export class PayloadHttpError extends BaseHttpError { /** * Default message is 'Storage quota was exceeded.'. + * * @param message - Optional, more specific, message. * @param options - Optional error options. */ diff --git a/src/util/errors/RangeNotSatisfiedHttpError.ts b/src/util/errors/RangeNotSatisfiedHttpError.ts index 0ee723a88..eec45ed2c 100644 --- a/src/util/errors/RangeNotSatisfiedHttpError.ts +++ b/src/util/errors/RangeNotSatisfiedHttpError.ts @@ -10,6 +10,7 @@ const BaseHttpError = generateHttpErrorClass(416, 'RangeNotSatisfiedHttpError'); export class RangeNotSatisfiedHttpError extends BaseHttpError { /** * Default message is 'The requested range is not supported.'. + * * @param message - Optional, more specific, message. * @param options - Optional error options. */ diff --git a/src/util/handlers/AsyncHandler.ts b/src/util/handlers/AsyncHandler.ts index a454d2ab9..b8110563c 100644 --- a/src/util/handlers/AsyncHandler.ts +++ b/src/util/handlers/AsyncHandler.ts @@ -9,6 +9,7 @@ export abstract class AsyncHandler { /** * Checks if the input can be handled by this class. * If it cannot handle the input, rejects with an error explaining why. + * * @param input - Input that could potentially be handled. * * @returns A promise resolving if the input can be handled, rejecting with an Error if not. @@ -21,6 +22,7 @@ export abstract class AsyncHandler { /** * Handles the given input. This may only be called if {@link canHandle} did not reject. * When unconditionally calling both in sequence, consider {@link handleSafe} instead. + * * @param input - Input that needs to be handled. * * @returns A promise resolving when handling is finished. @@ -31,6 +33,7 @@ export abstract class AsyncHandler { * Helper function that first runs {@link canHandle} followed by {@link handle}. * Throws the error of {@link canHandle} if the data cannot be handled, * or returns the result of {@link handle} otherwise. + * * @param input - Input data that will be handled if it can be handled. * * @returns A promise resolving if the input can be handled, rejecting with an Error if not. diff --git a/src/util/handlers/BooleanHandler.ts b/src/util/handlers/BooleanHandler.ts index 010d71a9e..acc5cffd1 100644 --- a/src/util/handlers/BooleanHandler.ts +++ b/src/util/handlers/BooleanHandler.ts @@ -15,6 +15,7 @@ export class BooleanHandler extends AsyncHandler { /** * Creates a new BooleanHandler that stores the given handlers. + * * @param handlers - Handlers over which it will run. */ public constructor(handlers: AsyncHandler[]) { diff --git a/src/util/handlers/ProcessHandler.ts b/src/util/handlers/ProcessHandler.ts index 2711ee4e3..43dc90e12 100644 --- a/src/util/handlers/ProcessHandler.ts +++ b/src/util/handlers/ProcessHandler.ts @@ -14,6 +14,7 @@ export class ProcessHandler extends AsyncHandler { /** * Creates a new ProcessHandler + * * @param source - The wrapped handler * @param clusterManager - The ClusterManager in use * @param executeOnPrimary - Whether to execute the source handler when the process is the _primary_ or a _worker_. diff --git a/src/util/handlers/WaterfallHandler.ts b/src/util/handlers/WaterfallHandler.ts index b3ef570b6..e0973c468 100644 --- a/src/util/handlers/WaterfallHandler.ts +++ b/src/util/handlers/WaterfallHandler.ts @@ -16,6 +16,7 @@ export class WaterfallHandler implements AsyncHandler { /** * Creates a new WaterfallHandler that stores the given handlers. + * * @param handlers - Handlers over which it will run. */ public constructor(handlers: AsyncHandler[]) { @@ -24,6 +25,7 @@ export class WaterfallHandler implements AsyncHandler { /** * Checks if any of the stored handlers can handle the given input. + * * @param input - The data that would need to be handled. * * @returns A promise resolving if at least 1 handler supports to input, or rejecting if none do. @@ -34,6 +36,7 @@ export class WaterfallHandler implements AsyncHandler { /** * Finds a handler that supports the given input and then lets it handle the given data. + * * @param input - The data that needs to be handled. * * @returns A promise corresponding to the handle call of a handler that supports the input. @@ -55,6 +58,7 @@ export class WaterfallHandler implements AsyncHandler { /** * Identical to {@link AsyncHandler.handleSafe} but optimized for composite * by only needing 1 canHandle call on members. + * * @param input - The input data. * * @returns A promise corresponding to the handle call of a handler that supports the input. diff --git a/src/util/locking/BaseReadWriteLocker.ts b/src/util/locking/BaseReadWriteLocker.ts index 5746f00fd..1f907a6c4 100644 --- a/src/util/locking/BaseReadWriteLocker.ts +++ b/src/util/locking/BaseReadWriteLocker.ts @@ -88,6 +88,7 @@ export abstract class BaseReadWriteLocker extends EqualReadWriteLocker { /** * Update the counter that keeps track of having open read locks there currently are. + * * @param identifier - Identifier on which to update the number of read locks. * @param mod - `+1` or `-1`. */ diff --git a/src/util/locking/EqualReadWriteLocker.ts b/src/util/locking/EqualReadWriteLocker.ts index 77e96c852..176efaa31 100644 --- a/src/util/locking/EqualReadWriteLocker.ts +++ b/src/util/locking/EqualReadWriteLocker.ts @@ -24,6 +24,7 @@ export class EqualReadWriteLocker implements ReadWriteLocker { /** * Acquires a new lock for the requested identifier. * Will resolve when the input function resolves. + * * @param identifier - Identifier of resource that needs to be locked. * @param whileLocked - Function to resolve while the resource is locked. */ diff --git a/src/util/locking/FileSystemResourceLocker.ts b/src/util/locking/FileSystemResourceLocker.ts index 2a738f41b..3173ba8cc 100644 --- a/src/util/locking/FileSystemResourceLocker.ts +++ b/src/util/locking/FileSystemResourceLocker.ts @@ -71,6 +71,7 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable, /** * Create a new FileSystemResourceLocker + * * @param args - Configures the locker using the specified FileSystemResourceLockerArgs instance. */ public constructor(args: FileSystemResourceLockerArgs) { @@ -85,7 +86,9 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable, * Wrapper function for all (un)lock operations. Any errors coming from the `fn()` will be swallowed. * Only `ENOTACQUIRED` errors wills be thrown (trying to release lock that didn't exist). * This wrapper returns undefined because {@link retryFunction} expects that when a retry needs to happen. + * * @param fn - The function reference to swallow errors from. + * * @returns Boolean or undefined. */ private swallowErrors(fn: () => Promise): () => Promise { @@ -138,7 +141,9 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable, /** * Map the identifier path to a unique path inside the {@link lockFolder}. + * * @param identifier - ResourceIdentifier to generate (Un)LockOptions for. + * * @returns Full path. */ private toLockfilePath(identifier: ResourceIdentifier): string { @@ -150,8 +155,10 @@ export class FileSystemResourceLocker implements ResourceLocker, Initializable, /** * Generate LockOptions or UnlockOptions depending on the type of defauls given. * A custom lockFilePath mapping strategy will be used. + * * @param identifier - ResourceIdentifier to generate (Un)LockOptions for * @param defaults - The default options. (lockFilePath will get overwritten) + * * @returns LockOptions or UnlockOptions */ private generateOptions(identifier: ResourceIdentifier, defaults: T): T { diff --git a/src/util/locking/RedisLocker.ts b/src/util/locking/RedisLocker.ts index 78176318e..377f30b8e 100644 --- a/src/util/locking/RedisLocker.ts +++ b/src/util/locking/RedisLocker.ts @@ -67,6 +67,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab /** * Creates a new RedisClient + * * @param redisClient - Redis connection string of a standalone Redis node * @param attemptSettings - Override default AttemptSettings * @param redisSettings - Addition settings used to create the Redis client or to interact with the Redis server @@ -93,6 +94,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab /** * Generate and return a RedisClient based on the provided string + * * @param redisClientString - A string that contains either a host address and a * port number like '127.0.0.1:6379' or just a port number like '6379'. */ @@ -116,7 +118,9 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab /** * Create a scoped Redis key for Read-Write locking. + * * @param identifier - The identifier object to create a Redis key for + * * @returns A scoped Redis key that allows cleanup afterwards without affecting other keys. */ private getReadWriteKey(identifier: ResourceIdentifier): string { @@ -125,7 +129,9 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab /** * Create a scoped Redis key for Resource locking. + * * @param identifier - The identifier object to create a Redis key for + * * @returns A scoped Redis key that allows cleanup afterwards without affecting other keys. */ private getResourceKey(identifier: ResourceIdentifier): string { @@ -138,6 +144,7 @@ export class RedisLocker implements ReadWriteLocker, ResourceLocker, Initializab * Wrapper function for all (un)lock operations. If the `fn()` resolves to false (after applying * {@link fromResp2ToBool}, the result will be swallowed. When `fn()` resolves to true, this wrapper * will return true. Any error coming from `fn()` will be thrown. + * * @param fn - The function reference to swallow false from. */ private swallowFalse(fn: () => Promise): () => Promise { diff --git a/src/util/locking/ResourceLocker.ts b/src/util/locking/ResourceLocker.ts index eb2fd8325..575200ab7 100644 --- a/src/util/locking/ResourceLocker.ts +++ b/src/util/locking/ResourceLocker.ts @@ -9,6 +9,7 @@ export interface ResourceLocker { /** * Acquires a lock on the requested identifier. * The promise will resolve when the lock has been acquired. + * * @param identifier - Resource to acquire a lock on. */ acquire: (identifier: ResourceIdentifier) => Promise; @@ -17,6 +18,7 @@ export interface ResourceLocker { * Releases a lock on the requested identifier. * The promise will resolve when the lock has been released. * In case there is no lock on the resource an error should be thrown. + * * @param identifier - Resource to release the lock on. */ release: (identifier: ResourceIdentifier) => Promise; diff --git a/src/util/locking/scripts/RedisLuaScripts.ts b/src/util/locking/scripts/RedisLuaScripts.ts index 1a99566b4..ccab3ff89 100644 --- a/src/util/locking/scripts/RedisLuaScripts.ts +++ b/src/util/locking/scripts/RedisLuaScripts.ts @@ -79,10 +79,13 @@ export type RedisAnswer = 0 | 1 | null | 'OK' | string; /** * Convert a RESP2 response to a boolean. + * * @param result - The Promise-wrapped result of a RESP2 Redis function. + * * @returns * `1`, `'OK'`: return `true` * * `0`: returns `false` * * `-ERR`: throw error + * * @throws On `-ERR*` `null` or any other value */ export async function fromResp2ToBool(result: Promise): Promise { @@ -123,12 +126,14 @@ export interface RedisReadWriteLock extends Redis { /** * Release readLock. This means decrementing the read counter with 1. + * * @returns 1 if succeeded. '-ERR' if read count goes below 0 */ releaseReadLock: (resourceIdentifierPath: string, callback?: Callback) => Promise; /** * Release writeLock. This means deleting the write lock. + * * @returns 1 if succeeded. '-ERR' if write lock was non-existing. */ releaseWriteLock: (resourceIdentifierPath: string, callback?: Callback) => Promise; @@ -145,6 +150,7 @@ export interface RedisResourceLock extends Redis { /** * Release lock. This means deleting the lock. + * * @returns 1 if succeeded. '-ERR' if lock was non-existing. */ releaseLock: (resourceIdentifierPath: string, callback?: Callback) => Promise; diff --git a/templates/scripts/util.js b/templates/scripts/util.js index f55e7716f..36b8d2172 100644 --- a/templates/scripts/util.js +++ b/templates/scripts/util.js @@ -71,6 +71,7 @@ function addPostListener(callback, formId = 'mainForm', errorId = 'error') { /** * Shows or hides the given element. + * * @param id - ID of the element. * @param visible - If it should be visible. */ @@ -88,6 +89,7 @@ function setVisibility(id, visible) { /** * Obtains all children, grandchildren, etc. of the given element. + * * @param element - Element to get all descendants from. */ function getDescendants(element) { @@ -96,6 +98,7 @@ function getDescendants(element) { /** * Updates the inner text and href field of an element. + * * @param id - ID of the element. * @param text - Text to put in the field(s). If this is undefined, instead the element will be hidden. * @param options - Indicates which fields should be updated. @@ -117,6 +120,7 @@ function updateElement(id, text, options) { /** * Fetches JSON from the url and converts it to an object. + * * @param url - URL to fetch JSON from. * @param redirectUrl - URL to redirect to in case the response code is >= 400. No redirect happens if undefined. */ @@ -159,6 +163,7 @@ function setError(message, errorId = 'error') { /** * Causes the page to redirect to a specific page when a button is clicked. + * * @param element - The id of the button. * @param url - The URL to redirect to. */ diff --git a/test/deploy/createAccountCredentials.ts b/test/deploy/createAccountCredentials.ts index 4e8949088..769c6c03f 100644 --- a/test/deploy/createAccountCredentials.ts +++ b/test/deploy/createAccountCredentials.ts @@ -29,6 +29,7 @@ const bob: User = { /** * Registers a user with the server and provides them with a pod. + * * @param user - The user settings necessary to register a user. */ async function register(user: User): Promise<{ webId: string; authorization: string }> { @@ -78,8 +79,10 @@ async function register(user: User): Promise<{ webId: string; authorization: str /** * Requests a client credentials API token. + * * @param webId - WebID to create credentials for. * @param authorization - Authorization header for the account that tries to create credentials. + * * @returns The id/secret for the client credentials request. */ async function createCredentials(webId: string, authorization: string): Promise<{ id: string; secret: string }> { @@ -104,6 +107,7 @@ async function createCredentials(webId: string, authorization: string): Promise< * Generates all the necessary data and outputs the necessary lines * that need to be added to the CTH environment file * so it can use client credentials. + * * @param user - User for which data needs to be generated. */ async function outputCredentials(user: User): Promise { diff --git a/test/integration/IdentityTestState.ts b/test/integration/IdentityTestState.ts index bd9439e1e..f320a9013 100644 --- a/test/integration/IdentityTestState.ts +++ b/test/integration/IdentityTestState.ts @@ -28,6 +28,7 @@ export class IdentityTestState { /** * Performs a fetch call while keeping track of the stored cookies and preventing redirects. + * * @param url - URL to call. * @param method - Method to use. * @param body - Body to send along. If this is not a string it will be JSONified. diff --git a/test/util/AccountUtil.ts b/test/util/AccountUtil.ts index aab8c1547..b683305b5 100644 --- a/test/util/AccountUtil.ts +++ b/test/util/AccountUtil.ts @@ -10,6 +10,7 @@ export type User = { /** * Registers an account for the given user details and creates one or more pods. + * * @param baseUrl - Base URL of the server. * @param user - User details to register. */ diff --git a/test/util/NotificationUtil.ts b/test/util/NotificationUtil.ts index cfafc2651..30dea393b 100644 --- a/test/util/NotificationUtil.ts +++ b/test/util/NotificationUtil.ts @@ -2,6 +2,7 @@ import { fetch } from 'cross-fetch'; /** * Subscribes to a notification channel. + * * @param type - The type of the notification channel, e.g., "NOTIFY.WebhookChannel2023". * @param webId - The WebID to spoof in the authorization header. This assumes the config uses the debug auth import. * @param subscriptionUrl - The subscription URL to which the request needs to be sent. @@ -36,6 +37,7 @@ export async function subscribe( /** * Verifies if a notification has the expected format. + * * @param notification - The (parsed) notification. * @param topic - The topic of the notification. * @param type - What type of notification is expected.