Function assertFunctionDocs

_tools/check_docs.ts:224–260

* Asserts that a function document has: * - A `@typeParam` tag for each type parameter. * - A code https://jsdoc.app/tags-param | @param tag for each parameter. * - A parameter definition inside the function for each @param tag. * - A code https://jsdoc.app/tags-returns | @returns

(
  document: DocNodeWithJsDoc<DocNodeFunction | ClassMethodDef>,
)

 *   a code snippet that executes successfully.
 */
function assertFunctionDocs(
  document: DocNodeWithJsDoc<DocNodeFunction | ClassMethodDef>,
) {
  for (const param of document.functionDef.params) {
    if (param.kind === "identifier") {
      assertHasParamTag(document, param.name);
    }
    if (param.kind === "rest" && param.arg.kind === "identifier") {
      assertHasParamTag(document, param.arg.name);
    }
    if (param.kind === "assign" && param.left.kind === "identifier") {
      assertHasParamTag(document, param.left.name);
    }
  }

  const documentedParams = document.jsDoc.tags?.filter((
    tag,
  ): tag is JsDocTagParam =>
    // Filter nested definitions like options.root as it is still documenting options parameter
    tag.kind === "param" && !tag.name.includes(".")
  ) ?? [];
  for (const param of documentedParams) {
    assertHasParamDefinition(document, param);
  }

  for (const typeParam of document.functionDef.typeParams) {
    assertHasTypeParamTags(document, typeParam.name);
  }
  if (
    document.functionDef.returnType !== undefined &&
    !isVoidOrPromiseVoid(document.functionDef.returnType) &&
    !isTypeAsserts(document.functionDef.returnType)
  ) {
    assertHasReturnTag(document);
  }
  assertHasExampleTag(document);
}

/**
 * Asserts that a class document has: