Feature Request: Instead of showing links to types/aliases/interfaces, show their information instead

[balupton]

I am converting a fairly large package to typescript today, and got typedoc generations docs. However the documentation requires a lot more clicking around to get the information that the jsdoc solution had previously.

Here is the declarations:
https://github.com/bevry/safeps/blob/4c9497e2b9eb53903ba12598e192c5ce1b931af5/source/index.ts#L25-L98

As you can see, there is a lot of shared properties between the interfaces. For three of them, I've already made what typedoc calls type aliases for them, which have the jsdoc descriptions.

However, when I navigate the documenation, I must click through several steps before I get the information. Each screenshot/visual-box is an additional click with typedoc:

I really like the way JSDoc embeds documentation, like it has done here for a different project: http://master.editions.bevry.surge.sh/docs/global.html#Edition

Or here via documentation.js for an earlier version of that project http://master.safeps.bevry.surge.sh/docs/#.safeps.exec

[aciccarello]

@balupton I agree that there are often too many clicks needed to view docs. It sounds like you want a way to inline types into their usage. For simple cases with one type or interface it wouldn't be too hard to inline the docs. How would you expect more complex union types to be handled. I'm not sure if there is a way to inline this functionality.

I think this should be tried as a plugin before we attempt implementing this in typedoc proper. Maybe an @inlineDoc annotation on the type/interface would be a good trigger.

[balupton]

@balupton I agree that there are often too many clicks needed to view docs. It sounds like you want a way to inline types into their usage. For simple cases with one type or interface it wouldn't be too hard to inline the docs. How would you expect more complex union types to be handled. I'm not sure if there is a way to inline this functionality. ...

@aciccarello thanks for the quick reply

Essentially I think that right now the documentation is focused on package author implementation details, rather than end user consumption details.

For instance, an end user doesn't care at all about intermediary types, only the types they will be writing and plugging into the calls.

So my expectation is for the documentation to cater towards the consumers / end users of the package, rather than the people who wrote the package.

To accomplish this, I'd imagine in the first screenshot, there is a table below "opts", with the union of the two types it mentions, and the childmost leafs of the types, so a table of the name, type, and description of each param that interface provides. If people want to get details on the implementation they can click through the existing line above the new table to follow through the details.

These consumption detail tables should be implemented for each interface. Having a annotation would mean I would end up annotating everything, a CLI flag would make more sense imho.

If this becomes common, it would be great for docs, as it means people can describe their types in the declaration files, and those descriptions make their way into documentation of packages that consume them. For instance, if the node.js declaration file exported /** comments along the types, then my interfaces that extend or union the builtin node.js types, would have descriptions on the builtin properties without every consumer having to describe them again, or not bothering.

I will finish converting my safeps package to typescript, and annotating all the types with their descriptions. Then if I have time, I'll send a mockup of what I'm after. However, it will essentially be the clarity that the jsdoc offerings already offer (from the links in the first post) with their nested tables, however with the ability to dive into the intermediary types if desired.

_{Sent with GitHawk}

[Gerrit0]

Closing this in favor of #1021.