search

denoland / deno_doc

Documentation generator for Deno
MIT License
262 stars 55 forks source link

[HTML] default exports don't respect `@internal` or `@ignore` JSDoc tags #590

Open nberlette opened 5 months ago

nberlette commented 5 months ago

When using deno doc for JSON or stdout output, anything I have tagged with @ignore or @internal is stripped from the generated documentation (as expected). It's not the same for generated HTML docs however, at least not when it comes to default exports from a module.

For some background here, I personally dislike the docs that are generated for modules with both named exports and a default export. It's redundant and also unclear, IMO, since the default don't really convey to the user that it's an alias for an item that's also exported by name. To an inexperienced user, they might think that "default" is actually a named import with the way the docs are presented currently.

Furthermore, the generated "usage" for default exports is obnoxious. It suggests that I use the code import . from "capitalize.ts"; (but that's a topic for another issue).

Getting back to the issue at hand, I've added /** @ignore */ and /** @internal */ (and even both) to my default exports in an attempt to exclude them from the generated docs. All with no effect.

Note: Based on a cursory scanning of the currently open issues, this seems potentially related to #522.

crowlKats commented 3 weeks ago

The default exports usage was fixed, however it wasn't perfect. this is improved in #642