Add warnings to provide documentation

[softwareantics]

My projects has some fairly strict rules around documentation. It would be neat to have some warnings around missing documentation for variables, functions, enums, etc.

[adam-coster]

Can you provide some examples of the kinds of cases you'd want to see error info for, and what info you'd want to see in the error messages?

[softwareantics]

We should implement support for the following warnings:

• A warning should be triggered when a description is missing for a variable, function, enumeration, etc.
• If a param/argument tag is missing for a function with parameters, a warning should be displayed.
  • Additionally, if the parameter type is not specified, a warning could be shown.
• A warning should be raised when no return type is specified for a function.
• Warnings should be generated where a type is not specified for variables, return types, etc.

Something as simple as:

Missing JSDoc description tag for {name here}
Missing JSDoc argument tag for type {function name - parameter name}
Missing JSDoc return tag for {function name here}

Furthermore, perhaps providing support for access modifiers or simply supporting /// @ignore would be a great addition, too :).

[adam-coster]

I like these, though since we don't have a strong desire for them ourselves they unfortunately won't be very high up on my priority queue.

---

For future reference for myself, or for anyone who wants to take a crack at this.

When functions are processed we already know if they have docs:

stitch/packages/parser/src/visitor.functionExpression.ts

Line 19 in 87783b9

const docs = ctx.docs || this.PROCESSOR.consumeJsdoc();

Logic could be added to look at the JSDoc contents, and add diagnostic errors via this.PROCESSOR.addDiagnostic().

Since not all users would want this, we'd need to add some Diagnostic containers specifically for this purpose to allow filtering:

stitch/packages/parser/src/project.diagnostics.ts

Line 7 in 87783b9

export interface DiagnosticCollections {

Those new collections would probably be something like:

• JSDOC_MISSING_DESCRIPTION
• JSDOC_MISSING_RETURN
• JSDOC_MISSING_PARAM
• JSDOC_MISSING_PARAM_TYPE

After all of that we'll be getting the new diagnostics. BUT, since most users won't want that extra diagnostic info we'd need to also update the extension to allow configuration of which diagnostics the user wants. Currently we DON'T have a config option for that, but that's definitely something we'll want at some point anyway. I'm not sure what the best way would be to handle that, but poking around at other extensions they seem to use fully separate config options for each entry (or otherwise use a separate config file from the VSCode config, a la eslint.

Having them in the Extension config would probably be best, though. The config entries could be something like "stitch.diagnostics.enable.JSDOC_MISSING_DESCRIPTION" booleans or something.

[softwareantics]

Is this something I could look at implementing?

[adam-coster]

Is this something I could look at implementing?

Definitely! It's complicated, especially if you aren't used to the Node.js ecosystem, so it'll take some doing. You can make a draft PR to ask questions as you go.

I haven't added much documentation for development setup, but that's something I can do sometimes this week to reduce initial friction

[softwareantics]

That sounds great, I'd love to see this feature through to the end.