Config option to exclude not explicitly documented symbols

[canonic-epicure]

It seems, currently the approach used by TypeDoc is that all symbols in the source files are included in the resulting documentation. It goes that far, that even symbols that are not exported from the module (and thus not accessible by the users) are also included by default, and one need to use special config to exclude them (excludeNotExported). So users need to explicitly opt-out for specific symbols.

It is probably a reasonable default for the internal documentation, that is supposed to be used by developers, working on the project. However, if the documentation is being written for the end users, the better default would be to opt-in for documentation and hide all symbols that are not explicitly documented.

consider this:

/**
 * This is my cool helper
 */
export function myHelper () : number {
    return helper1() + helper2() + helper3() + ... + helper10()
}

const helper1 = () => 1
const helper2 = () => 2
const helper3 = () => 3

Here the myHelper is a public function and all helperX are private. I'd like to have an option to only include myHelper in the docs, based on the fact, that it is explicitly documented, and, since the helperX helpers have no documentation comments, assume those are private.

[canonic-epicure]

PR: #996

[canonic-epicure]

Found one problem with the approach I chose - notably the enumeration members are not included, even if the parent enumeration has documentation. I'll peek a bit more

[canonic-epicure]

Any suggestion of how to check if a given ts.Node has a generated declaration, that has been included in docs?

[aciccarello]

Related to #639. What do you think about making this a separate mode instead of a flag? It's something that I suggested in #639 (comment). We probably need to discuss it more because the mode option is not well documented. Is there any reason you'd want to use this with namespaces?

[canonic-epicure]

I'm ok with --mode library instead of --exlcludeNotDocumented, as long it will do the same thing.

It seems this feature needs some fine-tuning, for example, it makes little sense to exclude enum members, even if those are not documented. I've tweaked the PR accordingly and currently in the process of writing docs for our project. Will be checking for other possible edge cases.

About namespaces - not sure. Never used them, as its basically a legacy feature of TypeScript if I'm correct. But same point applies to them - if something is not documented explicitly (in the namespace) it is considered private.

[DylanVann]

This could be taken slightly further, and allow only including members that have a block comment containing @public, this way you could document things internally, and not have them included in documentation for end users.

[aciccarello]

@DylanVann Currently TypeDoc uses @private and @protected to override the visibility defined by TypeScript so @public might be confusing. There is a plugin which adds a @include tag

There's also @hidden and @ignore which does the opposite and hides symbols.

[DylanVann]

@aciccarello I have seen those. If it was a new project those might work, but it's a pretty large project where we don't want to expose anything unintentionally (because the API is the contract with users).

I did manage to get it working using @samuraijack's work - DylanVann@0273693#diff-68d2486bc7e7d7e960c74fa3d9466b94R74

[canonic-epicure]

@DylanVann yes, make sense, I might adopt your changes as well.

[Gerrit0]

I don't think making this a new mode makes sense, this idea is a different feature request than #639. The proposed --excludeNotDocumented makes sense to me.

I'd like to see a test for undocumented enum members with a documented enum, but otherwise #966 looks good to me.

[aciccarello]

I would like to support the use case of not-outputting public APIs but wouldn't adding a library mode support this? The only complication would be that types that are referenced by a public api might cause the type to appear in the final output.

Thanks for the PR which helps me understand what you are looking for more clearly. I am concerned that it will be hard to have this flag fit enough people's needs to justify supporting it. What if someone else needs an adjustment to what symbols need to be checked.

I think we would be better off having a clear example of how to create a plugin to modify the reflections that are included.

[canonic-epicure]

A plugin idea sounds good for me.

[ELLIOTTCABLE]

Just 👍 on needing something like this!

Regarding broken links: I think, ideally, "hidden" or "not-included" items should be shipped in the HTML output, but hidden via a CSS property, or JS, or similar; this allows them to be shown on-demand IFF the URL-anchor includes their id. (In other words, "private" stuff doesn't clutter up the documentation; but is still visible if necessary, and links don't break.)

So, ideally,

1. @include, or another wording, becomes built-in,
2. the newly-added 'library' mode toggles only those objects which are tagged with neither @hidden nor @include,
3. and @hidden (or absent-@include) items are rendered into the documentation, and hidden client-side.

Thoughts?

(As a side-note: I'd be wary of stomping, specifically, on the word "include" for the above — as that precludes an intuitive "include external documentation for this item" feature in the future … but I suppose that's a small concern by comparison. ¯\_(ツ)_/¯)

[DylanVann]

I've migrated to using API Extractor.