JSDoc Documentation Coverage
Flags exported and internal symbols that lack a JSDoc description.
JSDoc descriptions are how exported symbols communicate intent across module boundaries. Tools like TypeScript's language server, hover tooltips, generated API documentation, and AI assistants all consume JSDoc blocks. Symbols without them require readers to open the declaration file to understand what the symbol does — which is slower and easier to misinterpret.
Vipr's documentation analysis raises the severity for exported symbols (they cross module boundaries) and lowers it for internal ones (the audience is smaller). Methods with multiple parameters get extra weight because positional argument lists are particularly error-prone without descriptions.
Severity guide
- info
- Symbol is internal with low parameter count — JSDoc would help but is not urgent.
- warning
- Exported symbol with multiple parameters is missing JSDoc. Callers will struggle to understand the parameter contract.
- critical
- Not currently emitted by this analysis.
Remediation
Add a /** description */ block above each flagged declaration. Include @param and @returns when there are non-obvious arguments.
- For exported symbols, write at least a one-line description of what the symbol does plus enough detail to use it correctly.
- For functions with multiple parameters, include
@paramblocks describing what each parameter represents. - For methods that return non-trivial values, include
@returnsso the type tooltip surfaces the meaning. - For classes, add a one-paragraph overview describing the class's responsibility and its lifecycle expectations.