(Deno doc) jsDoc is not being included for declared functions

[cknight]

Deno doc is not including jsDoc in it's output for declared functions. This is most obvious with the lack of any jsdoc showing for the functions at the top of https://doc.deno.land/https/github.com/denoland/deno/releases/latest/download/lib.deno.d.ts.

To take one specific example, in lib.deno.shared_global.ts, setTimeout is declared as:

/** Sets a timer which executes a function once after the timer expires. Returns
 * an id which may be used to cancel the timeout.
 *
 *     setTimeout(() => { console.log('hello'); }, 500);
 */
declare function setTimeout(...)

but the output of deno doc --json cli/js/lib.deno.ns.d.ts has null jsDoc:

  {
    "kind": "function",
    "name": "setTimeout",
    "location": {
      "filename": "file:///home/chris/dev/deno/cli/js/lib.deno.shared_globals.d.ts",
      "line": 182,
      "col": 8
    },
    "jsDoc": null,
    ...

[bartlomieju]

@cknight that's correct, currently only exported members are serialized. Implementing this functionality might require refactoring doc parser.

[SteelAlloy]

I have a somewhat similar problem: Comments from class methods and comments in objects are removed

/** some jsdoc */
export class name {
  /** some jsdoc */
  constructor() {
    
  }

  /** some jsdoc */
  method() {

  }
}

/** some jsdoc */
export const test = {
  /** some jsdoc */
  tag: () => {}
}

Is it intended?

[Pangoraw]

I investigated the problem with declare function .... The problem is that we try to find the leading comment by using the lower position of the function keyword and not the declare keyword. So it never finds a matching comment. However swc doesn't save the declare lower position, I tried (in https://github.com/Pangoraw/deno/commit/6584a70d32aa3192298d1a4e68f0ded47521717f) to use the function position minus 8 (the length of "declare" + a space) and this solves the problem for properly formatted .d.ts files (without only one space between declare and function).

/** some jsdoc */
declare function setTimeout(...);
^       ^---- we search here
└--- comment is here (8 bytes lower)

With https://github.com/Pangoraw/deno/tree/fix/declare-doc:

$ cargo run -- doc cli/js/lib.deno.shared_globals.d.ts
[...]
function setTimeout(cb: (args: any[]) => void, delay?: number, args: any[]): number
  Sets a timer which executes a function once after the timer expires. Returns an id which may be used to cancel the timeout.
      setTimeout(() => { console.log('hello'); }, 500);
[...]

I could either open an issue on swc to store the declare lower boundary or substract 8 bytes for each position (classes and variables as well).

[bartlomieju]

@Pangoraw SWC already handles declare - https://docs.rs/swc_ecma_ast/0.20.0/swc_ecma_ast/struct.FnDecl.html#structfield.declare

Fixing this issue requires to capture nodes that have declare keyword, in addition to currently handled export.

[Pangoraw]

Functions that are not using declare are already skipped (see https://github.com/denoland/deno/blob/master/cli/doc/parser.rs#L316-L318). The problem comes from the lower boundary of the function declaration span which does not take into account the 8+ bytes from the declare keyword. Declaration using export are handled differently in https://github.com/denoland/deno/blob/master/cli/doc/module.rs#L19 using the ModuleDecl wich is spanning the export keyword, that's why the js doc is exported for those without problems.