feat: Expose @Option for plugin use

Also exposes the necessary types + values to declare and set options.

Closes #1163
Closes #1165

Author: Gerrit0

src/index.ts

@@ -13,16 +13,36 @@ export { NavigationItem } from './lib/output/models/NavigationItem';
 export { UrlMapping } from './lib/output/models/UrlMapping';
 
 export {
+    SourceFileMode
+} from './lib/converter';
+
+export {
+    Option,
     Options,
     OptionsReader,
     ParameterHint,
     ParameterScope,
     ParameterType,
+
     TypeDocOptions,
+    TypeDocAndTSOptions,
+    TypeDocOptionMap,
+    KeyToDeclaration,
 
     TSConfigReader,
     TypeDocReader,
-    ArgumentsReader
+    ArgumentsReader,
+
+    DeclarationOption,
+
+    DeclarationOptionBase,
+    StringDeclarationOption,
+    NumberDeclarationOption,
+    BooleanDeclarationOption,
+    ArrayDeclarationOption,
+    MixedDeclarationOption,
+    MapDeclarationOption,
+    DeclarationOptionToOptionType
 } from './lib/utils/options';
 
 export { JSONOutput } from './lib/serialization';

src/lib/application.ts

@@ -26,6 +26,7 @@ import {
 import { Option, Options, ParameterType } from './utils';
 import { ParameterHint } from './utils/options';
 import { TypeDocAndTSOptions } from './utils/options/declaration';
+import { addDecoratedOptions } from './utils/options/sources';
 
 /**
  * The default TypeDoc main application class.
@@ -158,6 +159,8 @@ export class Application extends ChildableComponent<
         }
 
         this.plugins.load();
+        // Load decorated options from the plugins.
+        addDecoratedOptions(this.options);
 
         this.options.reset();
         this.options.setValues(options).mapErr(errors => {

src/lib/converter/index.ts

@@ -3,6 +3,8 @@ export { Converter } from './converter';
 
 export { convertDefaultValue, convertExpression } from './convert-expression';
 
+export { SourceFileMode } from './nodes';
+
 import './nodes/index';
 import './types/index';
 import './plugins/index';

src/lib/converter/nodes/index.ts

@@ -1,6 +1,6 @@
 export { AccessorConverter } from './accessor';
 export { AliasConverter } from './alias';
-export { BlockConverter } from './block';
+export { BlockConverter, SourceFileMode } from './block';
 export { ClassConverter } from './class';
 export { ConstructorConverter } from './constructor';
 export { EnumConverter } from './enum';

src/lib/utils/options/declaration.ts

@@ -32,7 +32,8 @@ export type TypeDocAndTSOptions = TypeDocOptions
     & Pick<CompilerOptions, Exclude<KnownKeys<CompilerOptions>, IgnoredTsOptionKeys>>;
 
 /**
- * Describes all TypeDoc options.
+ * Describes all TypeDoc options. Used internally to provide better types when fetching options.
+ * External consumers should likely use either [[TypeDocAndTSOptions]] or [[TypeDocOptions]].
  */
 export interface TypeDocOptionMap {
     options: string;

src/lib/utils/options/index.ts

@@ -1,4 +1,25 @@
 export { Options, OptionsReader } from './options';
 export { Option } from './sources';
 export { ArgumentsReader, TypeDocReader, TSConfigReader } from './readers';
-export { TypeDocOptions, ParameterType, ParameterHint, ParameterScope } from './declaration';
+export {
+    TypeDocOptions,
+    TypeDocAndTSOptions,
+
+    TypeDocOptionMap,
+    KeyToDeclaration,
+
+    ParameterType,
+    ParameterHint,
+    ParameterScope,
+
+    DeclarationOption,
+
+    DeclarationOptionBase,
+    StringDeclarationOption,
+    NumberDeclarationOption,
+    BooleanDeclarationOption,
+    ArrayDeclarationOption,
+    MixedDeclarationOption,
+    MapDeclarationOption,
+    DeclarationOptionToOptionType
+} from './declaration';

src/lib/utils/options/options.ts

@@ -160,7 +160,9 @@ export class Options {
         }
 
         for (const name of names) {
-            if (this.getDeclaration(name)) {
+            // Check for registering the same declaration twice, should not be an error.
+            const decl = this.getDeclaration(name);
+            if (decl && decl !== declaration) {
                 this._logger.error(`The option ${name} has already been registered`);
             } else {
                 this._declarations.set(name.toLowerCase(), declaration);

src/lib/utils/options/sources/decorator.ts

@@ -12,7 +12,18 @@ export function addDecoratedOptions(options: Options) {
  * Declares the given option and binds it to the decorated property.
  * @param option
  */
-export function Option<K extends keyof TypeDocOptionMap>(option: { name: K } & KeyToDeclaration<K>) {
+export function Option<K extends keyof TypeDocOptionMap>(option: { name: K } & KeyToDeclaration<K>);
+
+/**
+ * Declares the given option and binds it to the decorated property without strict checks.
+ *
+ * @privateRemarks
+ * Intended for plugin use only. SHOULD NOT BE USED INTERNALLY.
+ * @param option
+ */
+export function Option<K extends keyof TypeDocOptionMap>(option: DeclarationOption);
+
+export function Option(option: DeclarationOption) {
     declared.push(option);
 
     return function(target: { application: Application } | { options: Options }, key: PropertyKey) {

src/test/utils/options/options.test.ts

@@ -16,6 +16,15 @@ describe('Options', () => {
         equal(logger.hasErrors(), true);
     });
 
+    it('Does not error if the same declaration is registered twice', () => {
+        logger.resetErrors();
+        const declaration = { name: 'test-declaration', help: '' };
+        options.addDeclaration(declaration);
+        options.addDeclaration(declaration);
+        equal(logger.hasErrors(), false);
+        options.removeDeclarationByName(declaration.name);
+    });
+
     it('Supports removing a declaration by name', () => {
         options.addDeclaration({ name: 'not-an-option', help: '' });
         options.removeDeclarationByName('not-an-option');