implement jsdoc or other standardized and automatable doc tool

[vincerubinetti]

monarch-initiative/monarch-ui-new#68 @falquaddoomi made the comment:

Looks good. My only suggestion might be using JSDoc-style comments if we ever decide to run a documentation generator on the source and it's not too tedious for you. There are a bunch of options for parsing out the comments and generating documentation (Vuese, styleguidist, plugins for JSDoc), but I haven't tried any of them myself.

This would be helpful as a way to more consistently document components (and other things) in a consistent way. It also might be a good intermediate solution between no dedicated component docs and a full-blown storybook playground (overkill).

It might also allow for better editor integration? I already have prop types working, such that when using a component it will alert you if you're missing required props, or give an invalid value for a prop. It'd be cool if the IDE could also show the documentation along with it (e.g. "this component should be used in this circumstance").

I'd add that whatever the solution, it should be applicable to every vue component as well, even ones without a <script> tag. I should perhaps move my one-sentence description of components, which I've already done for most, from right before defineComponent to the top of the <template> so it's right at the top of the file.

[vincerubinetti]

To be clear, I feel pretty strongly that we don't really need actual doc pages for this app. We're not publishing a package of components here, and the number of people modifying this code will likely only ever be in the single digits. Also we're now nearing MVP, and we've basically hit the limit of amount of components we'll have, and it's not too many imo.

Reading more, it seems like jsdoc and typescript are kind of mutually exclusive, as jsdoc was largely created to define types before typescript existed. We're already getting nice editor intellisense for component props, function param and return types, etc.

However, I'd still like to implement JSDoc wherever possible, just because of @description and @example. It'd be really nice to see the description of a function available in a popup.

This will work great in .js/.ts files, but unfortunately it seems like you can't get a @description for a Vue component to show up in editor integration without installing more packages, which I would like to avoid. At least, it doesn't work with vetur and vue options api. Perhaps going to composition api and using volar instead will fix this.

[vincerubinetti]

An update to this with what I learned:

• The tag @description seems to be only necessary if you have other tags in the comment, like @param. Otherwise you can just do /** some text */ and that will show up as the description.
• I could stand to use more @param tags than I'm doing, but in most cases right now I think the argument names, argument typescript types, and function description do a good enough job at explaining what the arguments represent.
• There are @see and @link tags available, and I do reference quite a few external links. But the links show up in intellisense tooltips just fine without the tags, and they're clickable. Maybe these tags would be useful if we were generating docs.
• I could stand to use more @example tags maybe, but the place that would be most useful would be at the top level of component files, which happens to be one of the holes right now (see below)

With recent updates to the Volar extension for VS Code, these JSDoc comments work (they show in an intellisense tooltip) for almost anything, with just a few minor gaps.