From 6a762f0b3841b445b6b6b81d8918815511ec8c37 Mon Sep 17 00:00:00 2001 From: Gerrit Birkeland Date: Sun, 12 Jan 2020 21:51:58 -0700 Subject: [PATCH] feat: Expose `@Option` for plugin use Also exposes the necessary types + values to declare and set options. Closes #1163 Closes #1165 --- src/index.ts | 22 ++++++++++++++++++++- src/lib/application.ts | 3 +++ src/lib/converter/index.ts | 2 ++ src/lib/converter/nodes/index.ts | 2 +- src/lib/utils/options/declaration.ts | 3 ++- src/lib/utils/options/index.ts | 23 +++++++++++++++++++++- src/lib/utils/options/options.ts | 4 +++- src/lib/utils/options/sources/decorator.ts | 13 +++++++++++- src/test/utils/options/options.test.ts | 9 +++++++++ 9 files changed, 75 insertions(+), 6 deletions(-) diff --git a/src/index.ts b/src/index.ts index 1a04aaf8a..ba160bc43 100644 --- a/src/index.ts +++ b/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'; diff --git a/src/lib/application.ts b/src/lib/application.ts index daab48cf7..9c95ef799 100644 --- a/src/lib/application.ts +++ b/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 => { diff --git a/src/lib/converter/index.ts b/src/lib/converter/index.ts index a6421efb3..7f9e43756 100644 --- a/src/lib/converter/index.ts +++ b/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'; diff --git a/src/lib/converter/nodes/index.ts b/src/lib/converter/nodes/index.ts index bdf4e681f..e67fdab23 100644 --- a/src/lib/converter/nodes/index.ts +++ b/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'; diff --git a/src/lib/utils/options/declaration.ts b/src/lib/utils/options/declaration.ts index 1a2400b2f..984075525 100644 --- a/src/lib/utils/options/declaration.ts +++ b/src/lib/utils/options/declaration.ts @@ -32,7 +32,8 @@ export type TypeDocAndTSOptions = TypeDocOptions & Pick, 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; diff --git a/src/lib/utils/options/index.ts b/src/lib/utils/options/index.ts index 31dbeb43b..0cdda1b29 100644 --- a/src/lib/utils/options/index.ts +++ b/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'; diff --git a/src/lib/utils/options/options.ts b/src/lib/utils/options/options.ts index 92d09edae..80c12d11f 100644 --- a/src/lib/utils/options/options.ts +++ b/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); diff --git a/src/lib/utils/options/sources/decorator.ts b/src/lib/utils/options/sources/decorator.ts index 13c48372b..76cda86b4 100644 --- a/src/lib/utils/options/sources/decorator.ts +++ b/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(option: { name: K } & KeyToDeclaration) { +export function Option(option: { name: K } & KeyToDeclaration); + +/** + * 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(option: DeclarationOption); + +export function Option(option: DeclarationOption) { declared.push(option); return function(target: { application: Application } | { options: Options }, key: PropertyKey) { diff --git a/src/test/utils/options/options.test.ts b/src/test/utils/options/options.test.ts index 7a5925032..4ff963e4f 100644 --- a/src/test/utils/options/options.test.ts +++ b/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');