Report undocumented return values when using `validation.notDocumented`

[thislooksfun]

Search Terms

validation.notDocumented, parameter, return value

Problem

Now that validation.notDocumented has been fixed to work with functions (https://github.com/TypeStrong/typedoc/commit/98841f5b6c79a2314f5bde6d328fe0b6f4e56bea), it works pretty well. However, there are two more areas I would really like to see documentation checking for: parameters and return values. Specifically, the following code passes validation.notDocumented.

/** This is a stub comment */
export function doStuff(arg1: string, arg2: number): bool {
  return arg1.length > arg2;
}

/**
 * This is a stub comment
 *
 * @param arg
 * @returns
 */
export function doThings(arg: string): string {
  return arg;
}

I would love if it would complain about doStuff() missing @param and @return tags, and doThings() having them, but with no description.

Suggested Solution

Have validation.notDocumented check that @param and @returns tags both exist and have descriptions. That being said, two caveats I can think of:

1. @returns is meaningless on void functions and constructors, so those should be exempt.
2. It's possible that people might want to allow @param and/or @returns to be missing or empty, so it should probably be made an option. Maybe add types Parameter and ReturnValue (names tbd) to requiredToBeDocumented?

[Gerrit0]

Parameters are already doable - it just requires that you provide a custom requiredToBeDocumented that includes Parameter

https://github.com/TypeStrong/typedoc/blob/98841f5b6c79a2314f5bde6d328fe0b6f4e56bea/src/lib/utils/options/sources/typedoc.ts#L346-L378

Return values are... more annoying. They don't get a reflection of their own, so are a completely different case... It'll probably take me a while to come up with a design that fits and is reasonably configurable... in the meantime, easy to do with a plugin.

const td = require("typedoc");

exports.load = function (app) {
    app.converter.on(td.Converter.EVENT_RESOLVE, (context, reflection) => {
        if (
            reflection.kindOf(td.ReflectionKind.CallSignature) &&
            !(reflection.type?.type === "intrinsic" && reflection.type.name === "void") &&
            !reflection.comment?.returns
        ) {
            app.logger.warn(`${reflection.getFriendlyFullName()} does not contain an "@returns" block`);
        }
    });
};

[thislooksfun]

Ah, I was naïvely assuming that requiredToBeDocumented defaulted to including everything. As for the returns, is it possible to load a plugin without needing it to be its own npm package? If there is that would be fantastic, but if not I'll find a way.

[Gerrit0]

Yes, you can do that, if you give TypeDoc a path starting with . it'll look for the file relative to either cwd (if give on the command line) or relative to the configuration file defining it.

[Gerrit0]

I think I'm going to leave this one to plugin space. There's really not any difference between:

/** Returns the lowest non-negative number in nums */ 
export function f(nums: number[]): number {}

And

/** @returns the lowest non-negative number in nums */ 
export function f(nums: number[]): number {}

Except that the latter produces noisier documentation... I'd make a similar argument for parameters if the architecture didn't happen to make supporting them trivial. There's not much point to documenting sub-pieces of the api if they can be completely covered by other documentation.