Documenting "Top level" Interfaces

[tobiasschweizer]

I wonder if interfaces that are referenced by other interfaces could be put in a special section in the docs. So there would be something like top level interfaces and interfaces that can be used by these (reuse and combination of interfaces without redundancy).

interface part {
    a: string;
}

interface root {
    b: part;
}

So when creating the docs, I would like to hide part unless the user goes to root and looks up the type for its member b. part just by itself would never been used (only in combination with root).

For now, all the interfaces are listed in the same section which is not very clear.

[Gerrit0]

Separating individual documented items can be done through the @category tag. I don't think it makes sense right now to do more than that.

[tobiasschweizer]

Separating individual documented items can be done through the @category tag. I don't think it makes sense right now to do more than that.

I tried using the @category tag and it is great!
Will there be an option to ignore certain categories?

I am kind of hesitant to use @internal ...

[Gerrit0]

You can use @hidden or @ignore to hide reflections - there isn't any way to hide categories currently.

[tobiasschweizer]

But that would always hide them, right? The nice thing about @internal is that there is the --stripInternal flag which makes it flexible.

[Gerrit0]

Correct, maybe I'm missing something... what's your goal here? It might be worth opening a new issue to discuss adding more filtering options.

[tobiasschweizer]

The goal is that I can produce API docs for different purposes, depending on the categories. There are two target groups: people that simply use my lib in their projects and people that would like to develop it further.

For someone that is simple using my lib, a lot of classes etc. are not relevant. So it would be handy to simply exclude some categories using an option for typedoc, without touching the source of my project.

[tobiasschweizer]

If this seems reasonable to you, I will gladly file a feature request.

[Gerrit0]

That makes some sense - and I think some of your needs will likely be met by the 0.20 upgrade. In 0.20, typedoc will only document what you export from a given file, so for users, you could generate documentation only from your entry point, while for developers you could generate docs for the source directory, which would include all files.

That said - a hiddenCategories option seems reasonable, feel free to open an issue :)

[tobiasschweizer]

Ok, will do :-)

[tobiasschweizer]

@Gerrit0 issue created: #1407