Add option to warn on undocumented items (#1819)

Nokel81 · Gerrit0 · web-flow · commit 122fd72cada1 · 2022-01-22T21:03:09.000-07:00
* Add option to warn on undocumented items

* Fix skip node_modules

* fix off by one error

Signed-off-by: Sebastian Malton &lt;sebastian@malton.name&gt;

* Fix off by one error on reporting

* Fix changelog, change ignore node_modules check

Signed-off-by: Sebastian Malton &lt;sebastian@malton.name&gt;

* fix formatting

Signed-off-by: Sebastian Malton &lt;sebastian@malton.name&gt;

* fix circular dep

Signed-off-by: Sebastian Malton &lt;sebastian@malton.name&gt;

* Fix circular reference

* Actually fix circular dep

* Improve errors for invalid requiredToBeDocumented values

Co-authored-by: Gerrit Birkeland &lt;gerrit@gerritbirkeland.com&gt;
diff --git a/.config/regconfig.json b/.config/regconfig.json
@@ -2,7 +2,7 @@
     "core": {
         "workingDir": "dist/tmp/.reg",
         "actualDir": "dist/tmp/__screenshots__",
-        "thresholdRate": 0.001,
+        "thresholdRate": 0.01,
         "addIgnore": true,
         "ximgdiff": {
             "invocationType": "client"
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,9 +4,10 @@
 
 ### Features
 
+-   Added `--validation.notDocumented` option to warn on items that are not documented, #1817.
+-   Added new `cname` option for GitHub Pages custom domain support, #1803.
 -   `ReferenceType`s which reference an external symbol will now include `qualifiedName` and `package` in their serialized JSON.
 -   Added clickable anchor link for member titles, #1842.
--   Added new `cname` option for GitHub Pages custom domain support, #1803
 
 ### Bug Fixes
 
diff --git a/src/lib/application.ts b/src/lib/application.ts
@@ -34,6 +34,7 @@ import {
 } from "./utils/entry-point";
 import { nicePath } from "./utils/paths";
 import { hasBeenLoadedMultipleTimes } from "./utils/general";
+import { validateDocumentation } from "./validation/documentation";
 
 // eslint-disable-next-line @typescript-eslint/no-var-requires
 const packageInfo = require("../../package.json") as {
@@ -416,6 +417,14 @@ export class Application extends ChildableComponent<
             );
         }
 
+        if (checks.notDocumented) {
+            validateDocumentation(
+                project,
+                this.logger,
+                this.options.getValue("requiredToBeDocumented")
+            );
+        }
+
         // checks.invalidLink is currently handled when rendering by the MarkedLinksPlugin.
         // It should really move here, but I'm putting that off until done refactoring the comment
         // parsing so that we don't have duplicate parse logic all over the place.
diff --git a/src/lib/models/ReflectionGroup.ts b/src/lib/models/ReflectionGroup.ts
@@ -1,4 +1,4 @@
-import type { ReflectionKind } from "./reflections/abstract";
+import type { ReflectionKind } from "./reflections/kind";
 import type { ReflectionCategory } from "./ReflectionCategory";
 import type { DeclarationReflection } from ".";
 
diff --git a/src/lib/models/reflections/abstract.ts b/src/lib/models/reflections/abstract.ts
@@ -5,6 +5,7 @@ import type { Comment } from "../comments/comment";
 import { splitUnquotedString } from "./utils";
 import type { ProjectReflection } from "./project";
 import type { NeverIfInternal } from "../../utils";
+import { ReflectionKind } from "./kind";
 
 /**
  * Holds all data models used by TypeDoc.
@@ -32,79 +33,6 @@ export function resetReflectionID() {
     REFLECTION_ID = 0;
 }
 
-/**
- * Defines the available reflection kinds.
- */
-export enum ReflectionKind {
-    Project = 0x1,
-    Module = 0x2,
-    Namespace = 0x4,
-    Enum = 0x8,
-    EnumMember = 0x10,
-    Variable = 0x20,
-    Function = 0x40,
-    Class = 0x80,
-    Interface = 0x100,
-    Constructor = 0x200,
-    Property = 0x400,
-    Method = 0x800,
-    CallSignature = 0x1000,
-    IndexSignature = 0x2000,
-    ConstructorSignature = 0x4000,
-    Parameter = 0x8000,
-    TypeLiteral = 0x10000,
-    TypeParameter = 0x20000,
-    Accessor = 0x40000,
-    GetSignature = 0x80000,
-    SetSignature = 0x100000,
-    ObjectLiteral = 0x200000,
-    TypeAlias = 0x400000,
-    Event = 0x800000,
-    Reference = 0x1000000,
-}
-
-/** @hidden */
-export namespace ReflectionKind {
-    export const All = ReflectionKind.Reference * 2 - 1;
-
-    export const ClassOrInterface =
-        ReflectionKind.Class | ReflectionKind.Interface;
-    export const VariableOrProperty =
-        ReflectionKind.Variable | ReflectionKind.Property;
-    export const FunctionOrMethod =
-        ReflectionKind.Function | ReflectionKind.Method;
-    export const ClassMember =
-        ReflectionKind.Accessor |
-        ReflectionKind.Constructor |
-        ReflectionKind.Method |
-        ReflectionKind.Property |
-        ReflectionKind.Event;
-    export const SomeSignature =
-        ReflectionKind.CallSignature |
-        ReflectionKind.IndexSignature |
-        ReflectionKind.ConstructorSignature |
-        ReflectionKind.GetSignature |
-        ReflectionKind.SetSignature;
-    export const SomeModule = ReflectionKind.Namespace | ReflectionKind.Module;
-    export const SomeType =
-        ReflectionKind.Interface |
-        ReflectionKind.TypeLiteral |
-        ReflectionKind.TypeParameter |
-        ReflectionKind.TypeAlias;
-    export const SomeValue =
-        ReflectionKind.Variable |
-        ReflectionKind.Function |
-        ReflectionKind.ObjectLiteral;
-
-    /** @internal */
-    export const Inheritable =
-        ReflectionKind.Accessor |
-        ReflectionKind.IndexSignature |
-        ReflectionKind.Property |
-        ReflectionKind.Method |
-        ReflectionKind.Constructor;
-}
-
 export enum ReflectionFlag {
     None = 0,
     Private = 1,
diff --git a/src/lib/models/reflections/container.ts b/src/lib/models/reflections/container.ts
@@ -1,12 +1,8 @@
-import {
-    Reflection,
-    ReflectionKind,
-    TraverseCallback,
-    TraverseProperty,
-} from "./abstract";
+import { Reflection, TraverseCallback, TraverseProperty } from "./abstract";
 import type { ReflectionCategory } from "../ReflectionCategory";
 import type { ReflectionGroup } from "../ReflectionGroup";
 import type { DeclarationReflection } from "./declaration";
+import type { ReflectionKind } from "./kind";
 
 export class ContainerReflection extends Reflection {
     /**
diff --git a/src/lib/models/reflections/index.ts b/src/lib/models/reflections/index.ts
@@ -1,14 +1,14 @@
 export {
     Reflection,
-    ReflectionKind,
     ReflectionFlag,
-    TraverseProperty,
     ReflectionFlags,
+    TraverseProperty,
 } from "./abstract";
 export type { Decorator, TraverseCallback } from "./abstract";
 export { ContainerReflection } from "./container";
 export { DeclarationReflection } from "./declaration";
 export type { DeclarationHierarchy } from "./declaration";
+export { ReflectionKind } from "./kind";
 export { ParameterReflection } from "./parameter";
 export { ProjectReflection } from "./project";
 export { ReferenceReflection } from "./reference";
diff --git a/src/lib/models/reflections/kind.ts b/src/lib/models/reflections/kind.ts
@@ -0,0 +1,72 @@
+/**
+ * Defines the available reflection kinds.
+ */
+export enum ReflectionKind {
+    Project = 0x1,
+    Module = 0x2,
+    Namespace = 0x4,
+    Enum = 0x8,
+    EnumMember = 0x10,
+    Variable = 0x20,
+    Function = 0x40,
+    Class = 0x80,
+    Interface = 0x100,
+    Constructor = 0x200,
+    Property = 0x400,
+    Method = 0x800,
+    CallSignature = 0x1000,
+    IndexSignature = 0x2000,
+    ConstructorSignature = 0x4000,
+    Parameter = 0x8000,
+    TypeLiteral = 0x10000,
+    TypeParameter = 0x20000,
+    Accessor = 0x40000,
+    GetSignature = 0x80000,
+    SetSignature = 0x100000,
+    ObjectLiteral = 0x200000,
+    TypeAlias = 0x400000,
+    Event = 0x800000,
+    Reference = 0x1000000,
+}
+
+/** @hidden */
+export namespace ReflectionKind {
+    export const All = ReflectionKind.Reference * 2 - 1;
+
+    export const ClassOrInterface =
+        ReflectionKind.Class | ReflectionKind.Interface;
+    export const VariableOrProperty =
+        ReflectionKind.Variable | ReflectionKind.Property;
+    export const FunctionOrMethod =
+        ReflectionKind.Function | ReflectionKind.Method;
+    export const ClassMember =
+        ReflectionKind.Accessor |
+        ReflectionKind.Constructor |
+        ReflectionKind.Method |
+        ReflectionKind.Property |
+        ReflectionKind.Event;
+    export const SomeSignature =
+        ReflectionKind.CallSignature |
+        ReflectionKind.IndexSignature |
+        ReflectionKind.ConstructorSignature |
+        ReflectionKind.GetSignature |
+        ReflectionKind.SetSignature;
+    export const SomeModule = ReflectionKind.Namespace | ReflectionKind.Module;
+    export const SomeType =
+        ReflectionKind.Interface |
+        ReflectionKind.TypeLiteral |
+        ReflectionKind.TypeParameter |
+        ReflectionKind.TypeAlias;
+    export const SomeValue =
+        ReflectionKind.Variable |
+        ReflectionKind.Function |
+        ReflectionKind.ObjectLiteral;
+
+    /** @internal */
+    export const Inheritable =
+        ReflectionKind.Accessor |
+        ReflectionKind.IndexSignature |
+        ReflectionKind.Property |
+        ReflectionKind.Method |
+        ReflectionKind.Constructor;
+}
diff --git a/src/lib/models/reflections/project.ts b/src/lib/models/reflections/project.ts
@@ -1,5 +1,5 @@
 import { SourceFile, SourceDirectory } from "../sources/index";
-import { Reflection, ReflectionKind, TraverseProperty } from "./abstract";
+import { Reflection, TraverseProperty } from "./abstract";
 import { ContainerReflection } from "./container";
 import { splitUnquotedString } from "./utils";
 import { ReferenceReflection } from "./reference";
@@ -10,6 +10,7 @@ import { IntrinsicType } from "../types";
 import type { TypeParameterReflection } from "./type-parameter";
 import { removeIfPresent } from "../../utils";
 import type * as ts from "typescript";
+import { ReflectionKind } from "./kind";
 
 /**
  * A reflection that represents the root of the project.
diff --git a/src/lib/models/reflections/reference.ts b/src/lib/models/reflections/reference.ts
@@ -1,6 +1,7 @@
 import type * as ts from "typescript";
-import { Reflection, ReflectionKind } from "./abstract";
+import { Reflection } from "./abstract";
 import { DeclarationReflection } from "./declaration";
+import { ReflectionKind } from "./kind";
 import type { ProjectReflection } from "./project";
 
 /**
diff --git a/src/lib/models/reflections/signature.ts b/src/lib/models/reflections/signature.ts
@@ -1,13 +1,9 @@
 import { Type, ReflectionType, ReferenceType } from "../types";
-import {
-    Reflection,
-    TraverseProperty,
-    TraverseCallback,
-    ReflectionKind,
-} from "./abstract";
+import { Reflection, TraverseProperty, TraverseCallback } from "./abstract";
 import type { ParameterReflection } from "./parameter";
 import type { TypeParameterReflection } from "./type-parameter";
 import type { DeclarationReflection } from "./declaration";
+import type { ReflectionKind } from "./kind";
 
 export class SignatureReflection extends Reflection {
     /**
diff --git a/src/lib/models/reflections/type-parameter.ts b/src/lib/models/reflections/type-parameter.ts
@@ -1,6 +1,7 @@
 import type { Type } from "../types";
-import { Reflection, ReflectionKind } from "./abstract";
+import { Reflection } from "./abstract";
 import type { DeclarationReflection } from "./declaration";
+import { ReflectionKind } from "./kind";
 
 export class TypeParameterReflection extends Reflection {
     override parent?: DeclarationReflection;
diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts
@@ -3,6 +3,7 @@ import type { LogLevel } from "../loggers";
 import type { SortStrategy } from "../sort";
 import { isAbsolute, join, resolve } from "path";
 import type { EntryPointStrategy } from "../entry-point";
+import type { ReflectionKind } from "../../models/reflections/kind";
 
 export const EmitStrategy = {
     true: true, // Alias for both, for backwards compatibility until 0.23
@@ -116,6 +117,7 @@ export interface TypeDocOptionMap {
     /** @deprecated use validation.invalidLink */
     listInvalidSymbolLinks: boolean;
     validation: ValidationOptions;
+    requiredToBeDocumented: (keyof typeof ReflectionKind)[];
 }
 
 export type ValidationOptions = {
@@ -128,6 +130,10 @@ export type ValidationOptions = {
      * If set, TypeDoc will produce warnings about \{&amp;link\} tags which will produce broken links.
      */
     invalidLink: boolean;
+    /**
+     * If set, TypeDoc will produce warnings about declarations that do not have doc comments
+     */
+    notDocumented: boolean;
 };
 
 /**
diff --git a/src/lib/utils/options/sources/typedoc.ts b/src/lib/utils/options/sources/typedoc.ts
@@ -4,6 +4,7 @@ import { ParameterType, ParameterHint, EmitStrategy } from "../declaration";
 import { BUNDLED_THEMES, Theme } from "shiki";
 import { SORT_STRATEGIES } from "../../sort";
 import { EntryPointStrategy } from "../../entry-point";
+import { ReflectionKind } from "../../../models/reflections/kind";
 
 export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
     options.addDeclaration({
@@ -342,6 +343,40 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         help: "A list of types which should not produce 'referenced but not documented' warnings.",
         type: ParameterType.Array,
     });
+    options.addDeclaration({
+        name: "requiredToBeDocumented",
+        help: "A list of reflection kinds that must be documented",
+        type: ParameterType.Array,
+        validate(values) {
+            // this is good enough because the values of the ReflectionKind enum are all numbers
+            const validValues = Object.values(ReflectionKind).filter(
+                (v) => typeof v === "string"
+            );
+
+            for (const kind of values) {
+                if (validValues.includes(kind)) {
+                    throw new Error(
+                        `'${kind}' is an invalid value for 'requiredToBeDocumented'. Must be one of: ${validValues.join(
+                            ", "
+                        )}`
+                    );
+                }
+            }
+        },
+        defaultValue: [
+            "Enum",
+            "EnumMember",
+            "Variable",
+            "Function",
+            "Class",
+            "Interface",
+            "Property",
+            "Method",
+            "GetSignature",
+            "SetSignature",
+            "TypeAlias",
+        ],
+    });
 
     options.addDeclaration({
         name: "validation",
@@ -350,6 +385,7 @@ export function addTypeDocOptions(options: Pick<Options, "addDeclaration">) {
         defaults: {
             notExported: true,
             invalidLink: false,
+            notDocumented: false,
         },
     });
 }
diff --git a/src/lib/utils/sort.ts b/src/lib/utils/sort.ts
@@ -3,7 +3,7 @@
  * @module
  */
 
-import { ReflectionKind } from "../models/reflections/abstract";
+import { ReflectionKind } from "../models/reflections/kind";
 import type { DeclarationReflection } from "../models/reflections/declaration";
 
 export const SORT_STRATEGIES = [
diff --git a/src/lib/validation/documentation.ts b/src/lib/validation/documentation.ts
diff --git a/src/lib/validation/exports.ts b/src/lib/validation/exports.ts
diff --git a/src/test/utils/options/options.test.ts b/src/test/utils/options/options.test.ts
diff --git a/src/test/utils/options/readers/arguments.test.ts b/src/test/utils/options/readers/arguments.test.ts

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-import type { ReflectionKind } from "./reflections/abstract";`
	`1`	`+import type { ReflectionKind } from "./reflections/kind";`
`2`	`2`	`import type { ReflectionCategory } from "./ReflectionCategory";`
`3`	`3`	`import type { DeclarationReflection } from ".";`
`4`	`4`