Skip to content

Documenting "Top level" Interfaces #250

Closed
Closed
@tobiasschweizer

Description

@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.

Activity

Gerrit0

Gerrit0 commented on Nov 29, 2020

@Gerrit0
Collaborator

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

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

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

Gerrit0 commented on Dec 1, 2020

@Gerrit0
Collaborator

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

tobiasschweizer

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

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

Gerrit0

Gerrit0 commented on Dec 1, 2020

@Gerrit0
Collaborator

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

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

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

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

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

Gerrit0

Gerrit0 commented on Dec 1, 2020

@Gerrit0
Collaborator

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

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

Ok, will do :-)

tobiasschweizer

tobiasschweizer commented on Dec 1, 2020

@tobiasschweizer
Author

@Gerrit0 issue created: #1407

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    wontfixDeclining to implement

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

      Development

      No branches or pull requests

        Participants

        @tobiasschweizer@aciccarello@Gerrit0

        Issue actions

          Documenting "Top level" Interfaces · Issue #250 · TypeStrong/typedoc