deno doc - Ability to warn about missing explicit types in a library's public API
#19356
Labels
suggestion
suggestions for new features (yet to be agreed)
Comments
Merged
dsherret
added a commit
that referenced
this issue
Oct 31, 2023
Adds a new `--lint` flag to `deno doc` that surfaces three kinds of diagnostics: 1. Diagnostic for non-exported type referenced in an exported type. * Why? People often forget to export types from a module in TypeScript. To supress this diagnostic, add an `@internal` jsdoc tag to the internal type. 1. Diagnostic for missing return type or missing property type on a **public** type. * Why? Otherwise `deno doc` will not display good documentation. Adding explicit types also helps with type checking performance. 1. Diagnostic for missing jsdoc on a **public** type. * Why? Everything should be documented. This diagnostic can be supressed by adding a jsdoc comment description. If the lint passes, `deno doc` generates documentation as usual. For example, checking for deno doc diagnostics on the CI: ```shellsession $ deno doc --lint mod.ts second_entrypoint.ts > /dev/null ``` This feature is incredibly useful for library authors. ## Why not include this in `deno lint`? 1. The command needs the documenation output in order to figure out the diagnostics. 1. `deno lint` doesn't understand where the entrypoints are. That's critical for the diagnostics to be useful. 1. It's much more performant to do this while generating documentation. 1. There is precedence in rustdoc (ex. `#![warn(missing_docs)]`). ## Why not `--check`? It is confusing with `deno run --check`, since that means to run type checking (and confusing with `deno check --docs`). ## Output Future Improvement The output is not ideal atm, but it's fine for a first pass. We will improve it in the future. Closes denoland/deno_lint#972 Closes denoland/deno_lint#970 Closes #19356
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
It would be nice if there were a command like
deno doc --check mod.tsthat would point out everything in the public API used within a library that's missing explicit types.deno docworks off explicit types, so when they're missing the documentation will be lacking.For example, I ran a custom tool on Dax's repo and it helped me catch all these cases where explicit types were missing: https://github.com/dsherret/dax/pull/147/files
That said, perhaps this should be a linting error, but the issue is it would need to know the public entrypoint or entrypoints. You wouldn't want to bother having explicit types for everything.
The text was updated successfully, but these errors were encountered: