Configuration Management

/**
 * Main configuration object that defines TSDoc parsing behavior
 */
class TSDocConfiguration {
  constructor();
  
  /** All registered tag definitions */
  readonly tagDefinitions: ReadonlyArray<TSDocTagDefinition>;
  
  /** Subset of tag definitions that are supported */
  readonly supportedTagDefinitions: ReadonlyArray<TSDocTagDefinition>;
  
  /** Validation configuration for error reporting */
  readonly validation: TSDocValidationConfiguration;
  
  /** Supported HTML element names */
  readonly supportedHtmlElements: string[];
  
  /** Custom DocNode registry */
  readonly docNodeManager: DocNodeManager;
  
  /** All implemented TSDoc message IDs */
  readonly allTsdocMessageIds: ReadonlyArray<TSDocMessageId>;
  
  /** Reset configuration to initial state */
  clear(noStandardTags?: boolean): void;
  
  /** Add a custom tag definition to the configuration */
  addTagDefinition(tagDefinition: TSDocTagDefinition): void;
  
  /** Add multiple tag definitions at once with optional support setting */
  addTagDefinitions(tagDefinitions: ReadonlyArray<TSDocTagDefinition>, supported?: boolean): void;
  
  /** Look up a tag definition by name */
  tryGetTagDefinition(tagName: string): TSDocTagDefinition | undefined;
  
  /** Look up a tag definition by uppercase name for case-insensitive lookup */
  tryGetTagDefinitionWithUpperCase(tagNameWithUpperCase: string): TSDocTagDefinition | undefined;
  
  /** Check if a tag definition is supported */
  isTagSupported(tagDefinition: TSDocTagDefinition): boolean;
  
  /** Enable or disable support for a specific tag */
  setSupportForTag(tagDefinition: TSDocTagDefinition, supported: boolean): void;
  
  /** Enable or disable support for multiple tags */
  setSupportForTags(tagDefinitions: ReadonlyArray<TSDocTagDefinition>, supported: boolean): void;
  
  /** Set supported HTML elements and enable validation */
  setSupportedHtmlElements(htmlTags: string[]): void;
  
  /** Check if an HTML element is supported */
  isHtmlElementSupported(htmlTag: string): boolean;
  
  /** Check if a message ID is implemented by this TSDoc parser release */
  isKnownMessageId(messageId: TSDocMessageId | string): boolean;
}

import { TSDocConfiguration, StandardTags, TSDocMessageId } from "@microsoft/tsdoc";

// Create a new configuration
const configuration = new TSDocConfiguration();

// Access read-only properties
console.log(`Total tags: ${configuration.tagDefinitions.length}`);
console.log(`Supported tags: ${configuration.supportedTagDefinitions.length}`);

// Configure tag support
configuration.setSupportForTag(StandardTags.alpha, false);
configuration.setSupportForTags([StandardTags.beta, StandardTags.experimental], true);

// Check if a tag is supported
if (configuration.isTagSupported(StandardTags.beta)) {
  console.log("Beta tag is supported");
}

// Configure HTML element support
configuration.setSupportedHtmlElements(['b', 'i', 'code', 'a', 'br']);
console.log(configuration.isHtmlElementSupported('b')); // true
console.log(configuration.isHtmlElementSupported('script')); // false

// Check message ID validity
console.log(configuration.isKnownMessageId(TSDocMessageId.UnsupportedTag)); // true
console.log(configuration.isKnownMessageId('InvalidMessageId')); // false

// Access validation settings
configuration.validation.reportUnsupportedTags = true;
configuration.validation.ignoreUndefinedTags = false;

// Reset configuration
configuration.clear(); // Includes standard tags
configuration.clear(true); // Completely empty

/**
 * Defines the syntax and behavior of a TSDoc tag
 */
class TSDocTagDefinition {
  constructor(parameters: ITSDocTagDefinitionParameters);
  
  /** The name of the tag (e.g., "param", "returns") */
  readonly tagName: string;
  
  /** The syntax pattern for this tag */
  readonly syntaxKind: TSDocTagSyntaxKind;
  
  /** Whether multiple instances of this tag are allowed */
  readonly allowMultiple: boolean;
}

interface ITSDocTagDefinitionParameters {
  /** The name of the tag without the @ symbol */
  tagName: string;
  
  /** The syntax pattern for this tag */
  syntaxKind: TSDocTagSyntaxKind;
  
  /** Whether multiple instances are allowed (default: false) */
  allowMultiple?: boolean;
}

/**
 * Defines the syntax patterns for TSDoc tags
 */
enum TSDocTagSyntaxKind {
  /** Inline tags like {@link} or {@inheritDoc} */
  InlineTag = "InlineTag",
  
  /** Block tags like @param or @returns */
  BlockTag = "BlockTag",
  
  /** Modifier tags like @public or @beta */
  ModifierTag = "ModifierTag"
}

import { TSDocTagDefinition, TSDocTagSyntaxKind } from "@microsoft/tsdoc";

// Create a custom block tag
const customTag = new TSDocTagDefinition({
  tagName: "customNote",
  syntaxKind: TSDocTagSyntaxKind.BlockTag,
  allowMultiple: true
});

// Create a custom modifier tag
const deprecatedTag = new TSDocTagDefinition({
  tagName: "deprecated",
  syntaxKind: TSDocTagSyntaxKind.ModifierTag,
  allowMultiple: false
});

console.log(customTag.tagName); // "customNote"
console.log(customTag.allowMultiple); // true

/**
 * Configuration for validation rules and error reporting
 */
class TSDocValidationConfiguration {
  constructor();
  
  /** 
   * Set to true to silently ignore unrecognized tags instead of reporting a warning
   * @defaultValue false
   */
  ignoreUndefinedTags: boolean;
  
  /** 
   * Set to true to issue warnings for tags that are not supported by your tool
   * @defaultValue false
   */
  reportUnsupportedTags: boolean;
  
  /** 
   * Set to true to issue warnings for HTML elements not in supportedHtmlElements
   * @defaultValue false
   */
  reportUnsupportedHtmlElements: boolean;
}

import { TSDocConfiguration, TSDocValidationConfiguration } from "@microsoft/tsdoc";

const config = new TSDocConfiguration();
const validation = config.validation;

// Configure validation behavior
validation.ignoreUndefinedTags = true; // Don't warn about unknown tags
validation.reportUnsupportedTags = true; // Warn about unsupported standard tags
validation.reportUnsupportedHtmlElements = true; // Warn about unsupported HTML

// Use with parser
const parser = new TSDocParser(config);
const context = parser.parseString("/** @unknownTag content */");

// Check for validation messages
if (context.log.messages.length > 0) {
  console.log("Validation issues found:");
  context.log.messages.forEach(msg => {
    console.log(`${msg.messageId}: ${msg.messageText}`);
  });
}

/**
 * Registry for DocNode types and their definitions
 */
class DocNodeManager {
  constructor();
  
  /** Register custom DocNode definitions for a package */
  registerDocNodes(packageName: string, docNodeDefinitions: ReadonlyArray<IDocNodeDefinition>): void;
  
  /** Register allowable child relationships between node types */
  registerAllowableChildren(parentKind: string, childKinds: ReadonlyArray<string>): void;
  
  /** Check if a child node type is allowed under a parent node type */
  isAllowableChild(parentKind: string, childKind: string): boolean;
}

interface IDocNodeDefinition {
  /** The kind identifier for this DocNode type */
  docNodeKind: string;
  
  /** Constructor function for creating instances */
  constructor: DocNodeConstructor;
}

type DocNodeConstructor = new (...args: any[]) => DocNode;

import { DocNodeManager, DocNode } from "@microsoft/tsdoc";

// Custom DocNode class
class DocCustomTag extends DocNode {
  constructor(public readonly content: string) {
    super({ docNodeKind: "CustomTag" });
  }
  
  getChildNodes(): ReadonlyArray<DocNode | undefined> {
    return [];
  }
}

const manager = new DocNodeManager();

// Register custom node type
manager.registerDocNodes("my-package", [
  {
    docNodeKind: "CustomTag",
    constructor: DocCustomTag
  }
]);

// Define allowed relationships
manager.registerAllowableChildren("DocParagraph", ["CustomTag"]);

// Check relationships
const isAllowed = manager.isAllowableChild("DocParagraph", "CustomTag");
console.log(isAllowed); // true