@xpack/doxygen2docusaurus 1.1.0 → 2.1.0

package/src/doxygen/data-model/compounds/templateparamlisttype-dm.ts

@@ -0,0 +1,150 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2025-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/licenses/MIT.
+ */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+import * as util from 'node:util'
+
+import { DoxygenXmlParser } from '../doxygen-xml-parser.js'
+import { ParamDataModel } from './paramtype-dm.js'
+import { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="templateparamlistType">
+//   <xsd:sequence>
+//     <xsd:element name="param" type="paramType" minOccurs="0" maxOccurs="unbounded" />
+//   </xsd:sequence>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for template parameter list type data models.
+ *
+ * @remarks
+ * Represents template parameter list elements within Doxygen XML structures,
+ * corresponding to the templateparamlistType complex type in the XML schema.
+ * This class handles the parsing of parameter collections for templated
+ * constructs such as template classes and functions. All concrete template
+ * parameter list data model classes should extend this abstract base to
+ * ensure consistent parsing and data representation.
+ *
+ * @public
+ */
+// eslint-disable-next-line max-len
+export abstract class AbstractTemplateParamListType extends AbstractDataModelBase {
+  /**
+   * Collection of parameter data models within this template parameter list.
+   *
+   * @remarks
+   * Optional array containing parameter elements found within the template
+   * parameter list structure. Each parameter represents a template parameter
+   * definition including its type, name, and other attributes. The array
+   * supports zero to many parameters as per the XML schema, accommodating
+   * both non-templated constructs and complex template declarations.
+   */
+  params?: ParamDataModel[] | undefined
+
+  /**
+   * Constructs a new AbstractTemplateParamListType instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the template parameter list
+   * data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * Parses the provided XML element to extract template parameter list
+   * information including parameter collections. The constructor processes
+   * parameter elements into ParamDataModel instances when present. This
+   * element type has no attributes as per the XML schema definition,
+   * containing only parameter child elements.
+   */
+  constructor(xml: DoxygenXmlParser, element: object, elementName: string) {
+    super(elementName)
+
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+
+    // ------------------------------------------------------------------------
+    // Process elements.
+
+    const innerElements = xml.getInnerElements(element, elementName)
+    assert(innerElements.length > 0)
+
+    // console.log(util.inspect(item))
+    for (const innerElement of innerElements) {
+      if (xml.hasInnerText(innerElement)) {
+        // Ignore texts
+      } else if (xml.hasInnerElement(innerElement, 'param')) {
+        this.params ??= []
+        this.params.push(new ParamDataModel(xml, innerElement))
+      } else {
+        console.error(util.inspect(innerElement))
+        console.error(
+          `${elementName} element:`,
+          Object.keys(innerElement),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    // ------------------------------------------------------------------------
+    // Process attributes.
+
+    assert(!xml.hasAttributes(element))
+
+    // ------------------------------------------------------------------------
+
+    // console.log(util.inspect(this, { compact: false, depth: 999 }))
+  }
+}
+
+// ----------------------------------------------------------------------------
+
+// <xsd:element name="templateparamlist" type="templateparamlistType" minOccurs="0" />
+
+/**
+ * Concrete data model class for template parameter list elements.
+ *
+ * @remarks
+ * Represents individual template parameter list elements found within
+ * Doxygen compound XML structures. This class extends the abstract base
+ * to provide specific handling for 'templateparamlist' elements, which
+ * define the template parameters for templated constructs such as template
+ * classes, template functions, and template variables. Each template
+ * parameter list contains parameter definitions that specify the generic
+ * types and values used in template instantiation.
+ *
+ * @public
+ */
+export class TemplateParamListDataModel extends AbstractTemplateParamListType {
+  /**
+   * Constructs a new TemplateParamListDataModel instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the template parameter list
+   * data
+   *
+   * @remarks
+   * Initialises the template parameter list data model by parsing the
+   * provided XML element as a 'templateparamlist' element type. The
+   * constructor delegates to the parent class for common parameter list
+   * processing whilst specifying the element name for proper XML structure
+   * handling.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'templateparamlist')
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/doxygen/data-model/data-model.ts

@@ -0,0 +1,377 @@
+/*
+ * This file is part of the xPack project (http://xpack.github.io).
+ * Copyright (c) 2025-2026 Liviu Ionescu. All rights reserved.
+ *
+ * Permission to use, copy, modify, and/or distribute this software
+ * for any purpose is hereby granted, under the terms of the MIT license.
+ *
+ * If a copy of the license was not distributed with this file, it can
+ * be obtained from https://opensource.org/licenses/MIT.
+ */
+
+// ----------------------------------------------------------------------------
+
+import assert from 'node:assert'
+import * as fs from 'node:fs/promises'
+import * as path from 'node:path'
+import * as util from 'node:util'
+
+import { CliOptions } from '../../docusaurus/cli-options.js'
+import { CompoundDefDataModel } from './compounds/compounddef-dm.js'
+import { DoxygenFileDataModel } from './doxyfile/doxyfiletype-dm.js'
+import { DoxygenIndexDataModel } from './index/indexdoxygentype-dm.js'
+import { XmlElement } from './types.js'
+import { IndexCompoundDataModel } from './index/indexcompoundtype-dm.js'
+import { DoxygenDataModel } from './compounds/doxygentype-dm.js'
+import { MemberDefDataModel } from './compounds/memberdeftype-dm.js'
+import { DoxygenXmlParser } from './doxygen-xml-parser.js'
+
+// ----------------------------------------------------------------------------
+
+/**
+ * Top-level data model class for orchestrating Doxygen XML parsing and data
+ * organisation.
+ *
+ * @remarks
+ * This class serves as the primary entry point for parsing Doxygen-generated
+ * XML files and constructing a comprehensive data model. It coordinates the
+ * parsing of index files, compound definitions, and configuration files,
+ * maintaining references to all parsed content for subsequent processing.
+ * The class provides methods for sequential parsing operations and ensures
+ * data integrity throughout the parsing workflow.
+ *
+ * @public
+ */
+export class DataModel {
+  /**
+   * The global configuration options for the parsing operation.
+   *
+   * @remarks
+   * Contains command-line interface options that control the behaviour of
+   * the parser and influence how XML files are processed and data models
+   * are constructed.
+   */
+  options: CliOptions
+
+  /**
+   * The XML parser instance used for processing Doxygen XML files.
+   *
+   * @remarks
+   * Provides low-level XML parsing functionality and utility methods for
+   * extracting elements, attributes, and text content from the parsed XML
+   * structure.
+   */
+  xml: DoxygenXmlParser
+
+  /**
+   * Counter tracking the number of XML files successfully parsed.
+   *
+   * @remarks
+   * Incremented for each XML file processed during the parsing operation,
+   * providing metrics for progress monitoring and diagnostic reporting.
+   *
+   * @defaultValue 0
+   */
+  parsedFilesCounter = 0
+
+  /**
+   * The parsed Doxygen index data model from the main index XML file.
+   *
+   * @remarks
+   * Contains the top-level index structure that references all compound
+   * definitions and provides the navigation structure for the documentation.
+   * Populated during the initial parsing phase from `index.xml`.
+   */
+  doxygenindex?: DoxygenIndexDataModel // from index.xml
+
+  /**
+   * Collection of compound definition data models parsed from individual XML
+   * files.
+   *
+   * @remarks
+   * Each compound definition represents a documented entity such as a class,
+   * namespace, or file, along with its members and associated documentation.
+   * Populated by parsing XML files referenced in the index.
+   */
+  compoundDefs: CompoundDefDataModel[] // from `${'@_refid'}.xml`
+
+  /**
+   * The parsed Doxyfile configuration data model.
+   *
+   * @remarks
+   * Contains the Doxygen configuration options and settings that influenced
+   * the generation of the XML documentation. Parsed from `Doxyfile.xml` if
+   * present in the input folder.
+   */
+  doxyfile?: DoxygenFileDataModel // from Doxyfile.xml
+
+  /**
+   * The project version string extracted from the documentation metadata.
+   *
+   * @remarks
+   * Optional version identifier for the documented project, typically derived
+   * from the Doxygen configuration or project metadata during parsing.
+   */
+  projectVersion?: string
+
+  /**
+   * Constructs a new DataModel instance with the specified configuration
+   * options.
+   *
+   * @param options - The command-line interface options for controlling parsing
+   * behaviour
+   *
+   * @remarks
+   * Initialises the data model with the provided configuration options and
+   * creates a new DoxygenXmlParser instance for XML processing. The compound
+   * definitions array is initialised as empty and will be populated during
+   * the parsing phase.
+   */
+  constructor(options: CliOptions) {
+    this.options = options
+
+    this.xml = new DoxygenXmlParser(options)
+
+    this.compoundDefs = []
+  }
+
+  /**
+   * Orchestrates the complete parsing of Doxygen XML files and data model
+   * construction.
+   *
+   * @remarks
+   * This method performs the complete parsing workflow in sequential phases:
+   * parsing the main index file, processing all referenced compound XML files,
+   * and parsing the Doxyfile configuration. It maintains the original XML
+   * element order and content fidelity throughout the process. Progress
+   * information is logged to the console, with detailed output in verbose mode.
+   */
+  async parse(): Promise<void> {
+    // The parser is configured to preserve the original, non-trimmed content
+    // and the original elements order. The downsize
+    // Some details are from the schematic documentation:
+    // https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/README.md#documents
+    // The defaults are in the project source:
+    // https://github.com/NaturalIntelligence/fast-xml-parser/blob/master/src/xmlparser/OptionsBuilder.js
+
+    // ------------------------------------------------------------------------
+    // Parse the top index.xml file.
+
+    if (!this.options.verbose) {
+      console.log('Parsing Doxygen generated .xml files...')
+    }
+
+    await this.parseDoxygenIndex()
+
+    assert(this.doxygenindex !== undefined)
+
+    // ------------------------------------------------------------------------
+    // Parse all compound *.xml files mentioned in the index.
+
+    if (Array.isArray(this.doxygenindex.compounds)) {
+      for (const indexCompound of this.doxygenindex.compounds) {
+        // Parallelise not possible, the order is relevant.
+        // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+        const parsedDoxygenElements: XmlElement[] = await this.parseFile({
+          fileName: `${indexCompound.refid}.xml`,
+        })
+        // console.log(util.inspect(parsedDoxygen))
+        // console.log(JSON.stringify(parsedDoxygen, null, '  '))
+        this.processCompoundDefs(indexCompound, parsedDoxygenElements)
+      }
+
+      this.processMemberdefs()
+    }
+
+    // ------------------------------------------------------------------------
+    // Parse the Doxyfile.xml with the options.
+
+    await this.parseDoxyfile()
+
+    assert(this.doxyfile)
+
+    console.log(this.parsedFilesCounter, 'xml files parsed')
+    if (this.options.verbose) {
+      if (this.xml.images.length > 0) {
+        console.log(this.xml.images.length, 'images identified')
+      }
+    }
+  }
+
+  /**
+   * Parses the main Doxygen index XML file and initialises the index data
+   * model.
+   *
+   * @remarks
+   * This method reads and parses the `index.xml` file, ignoring the XML
+   * prologue and top-level text nodes. It extracts the `doxygenindex`
+   * element and constructs the corresponding data model. Any unrecognised
+   * elements are logged for diagnostic purposes.
+   */
+  async parseDoxygenIndex(): Promise<void> {
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const parsedIndexElements: XmlElement[] = await this.parseFile({
+      fileName: 'index.xml',
+    })
+    // console.log(util.inspect(parsedIndex))
+    // console.log(util.inspect(parsedIndex[0]['?xml']))
+    // console.log(JSON.stringify(parsedIndex, null, '  '))
+
+    for (const element of parsedIndexElements) {
+      if (this.xml.hasInnerElement(element, '?xml')) {
+        // Ignore the top xml prologue.
+      } else if (this.xml.hasInnerText(element)) {
+        // Ignore top texts.
+      } else if (this.xml.hasInnerElement(element, 'doxygenindex')) {
+        this.doxygenindex = new DoxygenIndexDataModel(this.xml, element)
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          'index.xml element:',
+          Object.keys(element),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+  }
+
+  /**
+   * Processes compound definitions from the parsed Doxygen XML elements.
+   *
+   * @param indexCompound - The compound index data model
+   * @param parsedDoxygenElements - The array of parsed XML elements for the
+   * compound
+   *
+   * @remarks
+   * This method iterates through the parsed XML elements, ignoring the XML
+   * prologue and top-level text nodes. For recognised `doxygen` elements, it
+   * constructs the compound definitions and appends them to the internal data
+   * model. Unrecognised elements are logged for further analysis.
+   */
+  processCompoundDefs(
+    indexCompound: IndexCompoundDataModel,
+    parsedDoxygenElements: XmlElement[]
+  ) {
+    for (const element of parsedDoxygenElements) {
+      if (this.xml.hasInnerElement(element, '?xml')) {
+        // Ignore the top xml prologue.
+      } else if (this.xml.hasInnerText(element)) {
+        // Ignore top texts.
+      } else if (this.xml.hasInnerElement(element, 'doxygen')) {
+        const doxygen = new DoxygenDataModel(this.xml, element)
+        if (Array.isArray(doxygen.compoundDefs)) {
+          this.compoundDefs.push(...doxygen.compoundDefs)
+        }
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          `${indexCompound.refid}.xml element:`,
+          Object.keys(element),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+  }
+
+  /**
+   * Processes member definitions and updates member kinds where necessary.
+   *
+   * @remarks
+   * This method traverses all compound definitions and their associated
+   * sections. It collects member definitions by their identifiers and, for
+   * each member with an empty kind, assigns the kind from the corresponding
+   * member definition. This ensures that all members are correctly classified
+   * within the internal data model.
+   */
+  processMemberdefs() {
+    const memberDefsById = new Map<string, MemberDefDataModel>()
+    for (const compoundDef of this.compoundDefs) {
+      if (compoundDef.sectionDefs !== undefined) {
+        for (const sectionDef of compoundDef.sectionDefs) {
+          if (sectionDef.memberDefs !== undefined) {
+            for (const memberDef of sectionDef.memberDefs) {
+              memberDefsById.set(memberDef.id, memberDef)
+            }
+          }
+          if (sectionDef.members !== undefined) {
+            for (const member of sectionDef.members) {
+              if (member.kind.length === 0) {
+                const memberDef = memberDefsById.get(member.refid)
+                assert(memberDef !== undefined)
+                member.kind = memberDef.kind
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Parses the Doxyfile XML and initialises the configuration data model.
+   *
+   * @remarks
+   * This method reads and parses the `Doxyfile.xml` file, ignoring the XML
+   * prologue and top-level text nodes. It extracts the `doxyfile` element and
+   * constructs the corresponding configuration data model. Any unrecognised
+   * elements are logged for diagnostic purposes.
+   */
+  async parseDoxyfile(): Promise<void> {
+    const parsedDoxyfileElements = (await this.parseFile({
+      fileName: 'Doxyfile.xml',
+    })) as XmlElement[]
+    // console.log(util.inspect(parsedDoxyfile))
+    // console.log(JSON.stringify(parsedDoxyfile, null, '  '))
+
+    for (const element of parsedDoxyfileElements) {
+      if (this.xml.hasInnerElement(element, '?xml')) {
+        // Ignore the top xml prologue.
+      } else if (this.xml.hasInnerElement(element, '#text')) {
+        // Ignore top texts.
+      } else if (this.xml.hasInnerElement(element, 'doxyfile')) {
+        this.doxyfile = new DoxygenFileDataModel(this.xml, element)
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          'Doxyfile.xml element:',
+          Object.keys(element),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+  }
+
+  // --------------------------------------------------------------------------
+  // Support methods.
+
+  /**
+   * Reads and parses the specified XML file, returning the parsed content.
+   *
+   * @param fileName - The name of the XML file to be parsed
+   * @returns A promise that resolves to the parsed XML content
+   *
+   * @remarks
+   * This method constructs the full file path using the configured input
+   * folder, reads the XML file as a UTF-8 string, and parses it using the
+   * configured XML parser. The method increments the internal counter for
+   * parsed files and, if verbose mode is enabled, logs the file being parsed.
+   */
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  async parseFile({ fileName }: { fileName: string }): Promise<any> {
+    const folderPath = this.options.doxygenXmlInputFolderPath
+    const filePath: string = path.join(folderPath, fileName)
+    const xmlString: string = await fs.readFile(filePath, { encoding: 'utf8' })
+
+    if (this.options.verbose) {
+      console.log(`Parsing '${fileName}'...`)
+    }
+    this.parsedFilesCounter += 1
+
+    return this.xml.xmlParser.parse(xmlString)
+  }
+}
+
+// ----------------------------------------------------------------------------