feat: `deno doc --lint` (#21032)

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 https://github.com/denoland/deno_lint/pull/972
Closes https://github.com/denoland/deno_lint/issues/970
Closes https://github.com/denoland/deno/issues/19356

1 files changed, 47 insertions, 1 deletions

diff --git a/cli/args/flags.rs b/cli/args/flags.rs
index 271a56ac3..0e4621d67 100644
--- a/cli/args/flags.rs
+++ b/cli/args/flags.rs
@@ -109,6 +109,7 @@ impl Default for DocSourceFileFlag {
 pub struct DocFlags {
   pub private: bool,
   pub json: bool,
+  pub lint: bool,
   pub source_files: DocSourceFileFlag,
   pub filter: Option<String>,
 }
@@ -1329,6 +1330,10 @@ Output documentation in JSON format:
 
     deno doc --json ./path/to/module.ts
 
+Lint a module for documentation diagnostics:
+
+    deno doc --lint ./path/to/module.ts
+
 Target a specific symbol:
 
     deno doc ./path/to/module.ts MyClass.someField
@@ -1363,7 +1368,14 @@ Show documentation for runtime built-ins:
             .long("filter")
             .help("Dot separated path to symbol")
             .required(false)
-            .conflicts_with("json"),
+            .conflicts_with("json")
+            .conflicts_with("lint"),
+        )
+        .arg(
+          Arg::new("lint")
+            .long("lint")
+            .help("Output documentation diagnostics.")
+            .action(ArgAction::SetTrue),
         )
         // TODO(nayeemrmn): Make `--builtin` a proper option. Blocked by
         // https://github.com/clap-rs/clap/issues/1794. Currently `--builtin` is
@@ -3145,11 +3157,13 @@ fn doc_parse(flags: &mut Flags, matches: &mut ArgMatches) {
     DocSourceFileFlag::Builtin
   };
   let private = matches.get_flag("private");
+  let lint = matches.get_flag("lint");
   let json = matches.get_flag("json");
   let filter = matches.remove_one::<String>("filter");
   flags.subcommand = DenoSubcommand::Doc(DocFlags {
     source_files,
     json,
+    lint,
     filter,
     private,
   });
@@ -6044,6 +6058,7 @@ mod tests {
           source_files: DocSourceFileFlag::Paths(vec!["script.ts".to_owned()]),
           private: false,
           json: false,
+          lint: false,
           filter: None,
         }),
         import_map_path: Some("import_map.json".to_owned()),
@@ -7298,6 +7313,7 @@ mod tests {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
           json: true,
+          lint: false,
           source_files: DocSourceFileFlag::Paths(vec![
             "path/to/module.ts".to_string()
           ]),
@@ -7320,6 +7336,7 @@ mod tests {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
           json: false,
+          lint: false,
           source_files: DocSourceFileFlag::Paths(vec![
             "path/to/module.ts".to_string()
           ]),
@@ -7336,6 +7353,7 @@ mod tests {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
           json: false,
+          lint: false,
           source_files: Default::default(),
           filter: None,
         }),
@@ -7355,6 +7373,7 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
+          lint: false,
           json: false,
           source_files: DocSourceFileFlag::Builtin,
           filter: Some("Deno.Listener".to_string()),
@@ -7376,6 +7395,7 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: true,
+          lint: false,
           json: false,
           source_files: DocSourceFileFlag::Paths(vec![
             "path/to/module.js".to_string()
@@ -7399,6 +7419,7 @@ mod tests {
       Flags {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
+          lint: false,
           json: false,
           source_files: DocSourceFileFlag::Paths(vec![
             "path/to/module.js".to_string(),
@@ -7423,6 +7444,31 @@ mod tests {
         subcommand: DenoSubcommand::Doc(DocFlags {
           private: false,
           json: false,
+          lint: false,
+          source_files: DocSourceFileFlag::Paths(vec![
+            "path/to/module.js".to_string(),
+            "path/to/module2.js".to_string()
+          ]),
+          filter: None,
+        }),
+        ..Flags::default()
+      }
+    );
+
+    let r = flags_from_vec(svec![
+      "deno",
+      "doc",
+      "--lint",
+      "path/to/module.js",
+      "path/to/module2.js"
+    ]);
+    assert_eq!(
+      r.unwrap(),
+      Flags {
+        subcommand: DenoSubcommand::Doc(DocFlags {
+          private: false,
+          lint: true,
+          json: false,
           source_files: DocSourceFileFlag::Paths(vec![
             "path/to/module.js".to_string(),
             "path/to/module2.js".to_string()