From 24415ee993a9c6e3c8f0dffa544f492dcb29463c Mon Sep 17 00:00:00 2001 From: ST-DDT Date: Sun, 24 Sep 2023 01:24:37 +0200 Subject: infra: lint all existing jsdocs (#2408) --- scripts/apidoc/apiDocsWriter.ts | 2 +- scripts/apidoc/markdown.ts | 4 ++++ scripts/apidoc/moduleMethods.ts | 5 +++++ scripts/apidoc/parameterDefaults.ts | 4 ++++ scripts/apidoc/signature.ts | 1 + scripts/apidoc/typedoc.ts | 11 ++++++++++- 6 files changed, 25 insertions(+), 2 deletions(-) (limited to 'scripts') diff --git a/scripts/apidoc/apiDocsWriter.ts b/scripts/apidoc/apiDocsWriter.ts index a736bd15..ca1ad927 100644 --- a/scripts/apidoc/apiDocsWriter.ts +++ b/scripts/apidoc/apiDocsWriter.ts @@ -199,7 +199,7 @@ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void { /** * Writes the api search index to the correct location. * - * @param project The typedoc project. + * @param pages The pages to write into the index. */ export function writeApiSearchIndex(pages: ModuleSummary[]): void { const apiIndex: APIGroup[] = [ diff --git a/scripts/apidoc/markdown.ts b/scripts/apidoc/markdown.ts index 7d44fc39..88df0150 100644 --- a/scripts/apidoc/markdown.ts +++ b/scripts/apidoc/markdown.ts @@ -47,7 +47,9 @@ function comparableSanitizedHtml(html: string): string { /** * Converts a Typescript code block to an HTML string and sanitizes it. + * * @param code The code to convert. + * * @returns The converted HTML string. */ export function codeToHtml(code: string): string { @@ -57,8 +59,10 @@ export function codeToHtml(code: string): string { /** * Converts Markdown to an HTML string and sanitizes it. + * * @param md The markdown to convert. * @param inline Whether to render the markdown as inline, without a wrapping `

` tag. Defaults to `false`. + * * @returns The converted HTML string. */ export function mdToHtml(md: string, inline: boolean = false): string { diff --git a/scripts/apidoc/moduleMethods.ts b/scripts/apidoc/moduleMethods.ts index 89f234db..33255a17 100644 --- a/scripts/apidoc/moduleMethods.ts +++ b/scripts/apidoc/moduleMethods.ts @@ -23,6 +23,7 @@ import { adjustUrls } from './utils'; * Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`. * * @param project The project used to extract the modules. + * * @returns The generated pages. */ export async function processModules( @@ -35,6 +36,7 @@ export async function processModules( * Analyzes and writes the documentation for a module and its methods such as `faker.animal.cat()`. * * @param module The module to process. + * * @returns The generated pages. */ async function processModule( @@ -63,6 +65,7 @@ async function processModule( * Analyzes the documentation for a class. * * @param module The class to process. + * * @returns The class information. */ export function analyzeModule(module: DeclarationReflection): { @@ -85,6 +88,7 @@ export function analyzeModule(module: DeclarationReflection): { * * @param module The module to process. * @param accessor The code used to access the methods within the module. + * * @returns A list containing the documentation for the api methods in the given module. */ export async function processModuleMethods( @@ -99,6 +103,7 @@ export async function processModuleMethods( * * @param signatures The signatures to process. * @param accessor The code used to access the methods. + * * @returns A list containing the documentation for the api methods. */ export async function processMethods( diff --git a/scripts/apidoc/parameterDefaults.ts b/scripts/apidoc/parameterDefaults.ts index b889fe24..7e02afc6 100644 --- a/scripts/apidoc/parameterDefaults.ts +++ b/scripts/apidoc/parameterDefaults.ts @@ -18,6 +18,9 @@ interface ParameterDefaultsAware extends Reflection { /** * TypeDoc EventCallback for EVENT_CREATE_DECLARATION events that reads the default parameters from the implementation. + * + * @param context The converter context. + * @param reflection The reflection to read the default parameters from. */ export const parameterDefaultReader: EventCallback = ( context: Context, @@ -44,6 +47,7 @@ export const parameterDefaultReader: EventCallback = ( * Removes compile expressions that don't add any value for readers. * * @param value The default value to clean. + * * @returns The cleaned default value. */ function cleanParameterDefault(value: string): string; diff --git a/scripts/apidoc/signature.ts b/scripts/apidoc/signature.ts index 2cba4904..113df911 100644 --- a/scripts/apidoc/signature.ts +++ b/scripts/apidoc/signature.ts @@ -314,6 +314,7 @@ async function signatureTypeToText( * Extracts and removed the parameter default from the comments. * * @param comment The comment to extract the default from. + * * @returns The extracted default value. */ function extractDefaultFromComment(comment?: Comment): string | undefined { diff --git a/scripts/apidoc/typedoc.ts b/scripts/apidoc/typedoc.ts index 268ae1f4..28a3db85 100644 --- a/scripts/apidoc/typedoc.ts +++ b/scripts/apidoc/typedoc.ts @@ -28,6 +28,7 @@ type CommentHolder = Pick; * Loads the project using TypeDoc. * * @param options The options to use for the project. + * * @returns The TypeDoc application and the project reflection. */ export function loadProject( @@ -75,6 +76,8 @@ function newTypeDocApp(): Application { * Selects the modules from the project that needs to be documented. * * @param project The project to extract the modules from. + * @param includeTestModules Whether to include test modules. + * * @returns The modules to document. */ export function selectApiModules( @@ -93,6 +96,7 @@ export function selectApiModules( * Selects the methods from the module that needs to be documented. * * @param module The module to extract the methods from. + * * @returns The methods to document. */ export function selectApiMethods( @@ -107,6 +111,7 @@ export function selectApiMethods( * Selects the signature from the method that needs to be documented. * * @param method The method to extract the signature from. + * * @returns The signature to document. */ export function selectApiSignature( @@ -124,7 +129,8 @@ export function selectApiSignature( * Selects the method signatures from the module that needs to be documented. * Method-Name -> Method-Signature * - * @param method The module to extract the method signatures from. + * @param module The module to extract the method signatures from. + * * @returns The method signatures to document. */ export function selectApiMethodSignatures( @@ -206,6 +212,7 @@ export function extractSourcePath( * * @param tag The tag to extract the text from. * @param reflection The reflection to extract the text from. + * @param tagProcessor The function used to extract the text from the tag. */ export function extractTagContent( tag: `@${string}`, @@ -285,6 +292,8 @@ export function extractSeeAlsos(reflection?: CommentHolder): string[] { /** * Joins the parts of the given jsdocs tag. + * + * @param tag The tag to join the parts of. */ export function joinTagContent(tag: CommentTag): string[] { return [joinTagParts(tag?.content)]; -- cgit v1.2.3