Not properly generating JSDoc documentation.

[mattd3v]

A few things seem off about the documentation generator.

This example code was run with Deno v1.0.2 on MacOS Catalina:

/**
 * Boolean helper functions.
 */

/** Returns a boolean representing if its argument was true. */
export function isTrue (bool: boolean): boolean {
  return bool || false;
}

/** Returns a boolean representing if its argument was false. */
export function isFalse (bool: boolean): boolean {
  return !isTrue(bool);
}

function isFalse(bool: boolean): boolean
  Returns a boolean representing if its argument was false.

function isTrue(bool: boolean): boolean
  Boolean helper functions.

The documentation text for the isTrue function actually contains the file header comment.

Also, when using export { isTrue, isFalse } the doc command yields no output, as if the exports weren't even there.

I have spent some time now familiarizing myself with the cli/doc source code, and can help out here. However, pointers from @bartlomieju and @lucacasonato would be much appreciated!

[lucacasonato]

Would be super awesome if you could get that working, but it's probably going to be somewhat challenging because of variable hoisting. But a first pass with no hoisting support would already be great.

Ref #4516

[bartlomieju]

The documentation text for the isTrue function actually contains the file header comment.

@mattd3v Definitely a bug - we need to add a test case for this situation.

Also, when using export { isTrue, isFalse } the doc command yields no output, as if the exports weren't even there.

Correct, this situation is still not handled.

Here's documentation for AST node for export { isTrue, isFalse }:
https://docs.rs/swc_ecma_ast/0.20.0/swc_ecma_ast/struct.NamedExport.html

Named exports should be parsed and then. based on collected specifiers, proper declarations from module body should be extracted.

[mattd3v]

I'm getting much more comfortable with the cli/doc code, and will implement named exports.

However, @bartlomieju I noticed the CLI automatically calls format_jsdoc with the value true for the truncated parameter. The CLI doesn’t seem capable of calling doc without truncation yet, but I could add a flag. Has there been any discussion on what the default should be?

/**
 * Print a custom greeting
 * by providing a name.
 *
 * @param {string} name
 */
export function greet(name) {
  console.log(`Hello, ${name}`);
}

Running the doc command on the above yields:

$ deno doc greet.js
function greet(name)
  Print a custom greeting by providing a name.

[bartlomieju]

@mattd3v I'm not sure, I think that was added by @lucacasonato to save some space in terminal (to replicate how go doc works), but there's already been a report that it's surprising behavior (#4755). I guess we could remove it altogether and always show full contents.

[mattd3v]

@bartlomieju can this be closed, or are there any other changes you know need to be made?