suggestion: expand the functionality of `deno doc --lint`

[iuioiua]

Such as:

1. Ensure all type parameters are documented with a @typeParam or @template tag.
2. Ensure all parameters are documented with a @param, @arg, or @argument tag.
3. Ensure all functions and methods are documented with a @returns tag.
4. Ensure all symbols have at least one @example tag.

This would significantly improve the quality of package documentation. We currently compensate for this missing functionality in the Standard Library by implementing our own doc checker.

If approved, I'd happily help with these efforts.

CC @dsherret

[iuioiua]

I talked with @kt3k; he also thinks this might be a good idea.

[dsherret]

I think we might want to consider moving deno doc --lint into the deno lint sub command and only have it active on packages that specify exports. It would be nice to be able to selectively ignore these rules. For example, I don't want to document all these type parameters in deno std:

export function parseArgs<
  TArgs extends Values<
    TBooleans,
    TStrings,
    TCollectable,
    TNegatable,
    TDefaults,
    TAliases
  >,
  TDoubleDash extends boolean | undefined = undefined,
  TBooleans extends BooleanType = undefined,
  TStrings extends StringType = undefined,
  TCollectable extends Collectable = undefined,
  TNegatable extends Negatable = undefined,
  TDefaults extends Record<string, unknown> | undefined = undefined,
  TAliases extends Aliases<TAliasArgNames, TAliasNames> | undefined = undefined,
  TAliasArgNames extends string = string,
  TAliasNames extends string = string,
>(
  args: string[],
  {
    "--": doubleDash = false,
    alias = {} as NonNullable<TAliases>,
    boolean = false,
    default: defaults = {} as TDefaults & Defaults<TBooleans, TStrings>,
    stopEarly = false,
    string = [],
    collect = [],
    negatable = [],
    unknown: unknownFn = (i: string): unknown => i,
  }: ParseOptions<
    TBooleans,
    TStrings,
    TCollectable,
    TNegatable,
    TDefaults,
    TAliases,
    TDoubleDash
  > = {},
): Args<TArgs, TDoubleDash> {

[dsherret]

I guess being forced to document that isn't so bad now that I think about it more.

[dsherret]

This will be a bit much though. For example, in some of my projects I wouldn't have time to go through adding examples for everything:

Ensure all symbols have at least one @example tag.

It would be nice to be able to be able to opt-out of certain rules and deno lint provides all that functionality already.

[iuioiua]

I think it's possible deno doc --lint users will be fine without opt-out. The command is opt-in and likely used by those who want the best for their documentation. It might be worth expanding deno doc --lint until we see sufficient evidence of demand for opt-out, which may never come.

[iuioiua]

Perhaps, running code snippets can be done with deno test --doc and the rest with deno doc --lint.

[NfNitLoop]

Ensure all type parameters are documented with a @typeParam or @template tag. Ensure all parameters are documented with a @param, @arg, or @argument tag. Ensure all functions and methods are documented with a @returns tag. Ensure all symbols have at least one @example tag.

I've worked in several codebases that had strict lints like this, and they end up with a lot of useless boilerplate like:

/**
 * Foo the bar according to baz. (Something that makes sense in the problem domain.)
 * 
 * @param foo the foo
 * @param bar the bar
 * @param baz the baz
 * @returns a Value.
 */
function doThing(foo: Foo, bar: Bar, baz: Baz): Value {

👍 for gentle reminders that I forgot to document an exported symbol. 👎 to the above kind of tedium.

Without a way to configure deno doc --lint's ruleset, adding such rules would probably make me just avoid using it altogether.