Missing Feature: Theory of Operation

[b-jsshapiro]

JSDoc does not have a good way to describe "theory of operation". Types? Yes. APIs? Sort of. Conceptual explanations? Not really. The closest thing seems to be abusing modules. There is a mechanism to incorporate a README file, but apparently only one. Tutorials aren't really the same thing, because (a) they are external, and (b) links to items documented within JSDoc are not readily available or maintained. Because of this lack, JSDoc is good at describing the what, but weak at describing the why or the rationale.

Similar systems, notably doxygen, have a notion that "pages" can be incorporated in the site. These can be targets or sources of links in the usual way. These pages are organized in a separate, top-level group.

Since we already have a markdown plugin that does most of the work, it does not seem like it would be a big lift to add a new top-level section "Topics" populated from markdown pages. Designated markdown files would be handled as follows:

• The customary markdown headers section (the --- enclosed section at the top) would define the menu item using @topic, giving a JSDoc namepath in the same way that the existing @module tag does.
• Markdown files would be processed to translate namepath targets in the same way this is currently done for markdown-enriched documentation.
• Pages are created by translating the markdown to static HTML. These become part of the generated site.
• Since the markdown files themselves consist exclusively of documentation, the content in these markdown files does not need to be enclosed in comments.

Though I have not looked in detail, I suspect this could be handled by a plugin.

Is there already a plugin that does this sort of thing?

If not, do others agree that this would be useful? It's very tedious to hack around this limitation.