infra: lint all existing jsdocs (#2408)

6 files changed, 25 insertions, 2 deletions

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 `<p>` 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<Reflection, 'comment'>;
  * 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)];