Module-less Category Descriptions / Class Summaries

johnameyer commented 2 days ago

Search Terms

@categoryDescription @summary

Problem

When first coming to a documentation, users might want to get a "lay of the land" and understand what classes of things a package contains.

Many packages may organize their files within a package into directories while only exposing a single index.js. While users can manually group these files together using @category on the individual members, no summary / module page will be created and so there is no place to see the top line summary of that categoryDescription or @summary of the classes, which makes it hard to get that "lay of the land" perspective.

Check out the core package of my docs for examples of what I am trying to achieve with the Controllers and Game Builder categories.

Suggested Solution

There's a few different ways to solve this generally as I see:

Show @categorySummary / @summary / useFirstParagraphOfCommentAsSummary on the package README / index page
Generate index / module pages for categories
Allow for categorizing files with a single "module" @category in internal (i.e. non-entrypoint) index.js
Allow for defining @categoryDescription in a non-module place (index.js?)
Allow for specifying a README for a category like the package root

Gerrit0 commented 2 days ago

TypeDoc sites always have at least one module page, even if you have a readme page, it can be reached by going to modules.html, which is linked in the navigation sidebar as the package name.

If you want that page to be the main page of the docs, you can do that by setting --readme none, optionally using the @include tag to reference the readme within the module comment for that file.

johnameyer commented 2 days ago

Right - my ask is around how to document categories within a module / package to have the same level of detail a module would have

Gerrit0 commented 1 day ago

I'm not sure I understand...

Show @categorySummary / @summary / useFirstParagraphOfCommentAsSummary on the package README / index page

This is how TypeDoc works today for the package's module page:

```diff diff --git a/packages/core/src/index.ts b/packages/core/src/index.ts index 6259d78..1b58960 100644 --- a/packages/core/src/index.ts +++ b/packages/core/src/index.ts @@ -1,3 +1,8 @@ +/** + * @module + * @categoryDescription Controller + * A controller is a class... + */ export * from './browser-index.js'; export { InquirerPresenter } from './intermediary/inquirer-presenter.js'; ```

Generate index / module pages for categories Allow for specifying a README for a category like the package root

Doing this raises a lot of questions... can you @link to those pages? What does the current module page look like then, does it contain duplicate information or links to the category pages, basically making it useless? What about groups, do they get their own pages? What if categorizeByGroup is true and the site includes both categories and groups, how does linking work then? Do you get a page per group and per category, or per group+category? Allowing this would require a major architecture change on the order of adding support for @document as TypeDoc expects pages to be generated according to reflection children, which this breaks entirely... not saying it can't happen, just that it isn't an easy change...

Allow for categorizing files with a single "module" @category in internal (i.e. non-entrypoint) index.js

This goes contrary to TypeDoc's philosophy of following entrypoint exports to determine documentation, and definitely won't be implemented.

Allow for defining @categoryDescription in a non-module place (index.js?)

I don't understand what this means... category descriptions are always owned by the parent of the categorized members so that there is an obvious single place of definition. Maybe I'm missing some reason here...?

johnameyer commented 1 day ago

Show @categorySummary / @summary / useFirstParagraphOfCommentAsSummary on the package README / index page

Ah don't think I would've figured out that I can add all of my @categorySummary to the entrypoint file - nifty and thanks!

Based on the documentation for @summary, I am a bit surprised the member summaries are not appearing on the module page though.

Generate index / module pages for categories Allow for specifying a README for a category like the package root

I don't think @link supports linking to files from what I've read in the docs and tried, but I just tried linking with a standard markdown link and that does seem to work. {@include} / {@includeCode} doesn't seem to work in category descriptions either.

I would think the module page would be more of an overview page and the group page would allow for more details / member summaries. If all the content would be included on the main module page then it could easily become long with a lot of included summaries or markdown documents...

You raise a lot of good questions otherwise... I think my comprehension of the differences between categories and groups isn't particularly strong enough so I'd rely on your judgement.

Would you have any other recommendations?

Allow for categorizing files with a single "module" @category in internal (i.e. non-entrypoint) index.js

For my use case then, would it make more sense to point typedoc directly to the various internal index.ts packages? Manually specifying categories is a bit tedious and easy enough to forget. Or is there some other mechanism possible (e.g categorizing based on folder structure)?

Allow for defining @categoryDescription in a non-module place (index.js?)

I think you helped clear this up for me with your response to the first point.

TypeStrong / typedoc