@xpack/doxygen2docusaurus 2.0.0 → 2.2.0

package/src/doxygen/data-model/index/indexcompoundtype-dm.ts

@@ -0,0 +1,256 @@
+/*
+ * 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 { IndexMemberDataModel } from './indexmembertype-dm.js'
+import { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="CompoundType">
+//   <xsd:sequence>
+//     <xsd:element name="name" type="xsd:string"/>
+//     <xsd:element name="member" type="MemberType" minOccurs="0" maxOccurs="unbounded"/>
+//   </xsd:sequence>
+//   <xsd:attribute name="refid" type="xsd:string" use="required"/>
+//   <xsd:attribute name="kind" type="CompoundKind" use="required"/>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for index compound type data models.
+ *
+ * @remarks
+ * Represents compound elements found within Doxygen index XML structures,
+ * corresponding to the CompoundType complex type in the XML schema. This
+ * class handles the parsing of compound names, member collections, and
+ * mandatory attributes (refid and kind). All concrete compound data model
+ * classes should extend this abstract base to ensure consistent parsing
+ * and data representation.
+ *
+ * @public
+ */
+export abstract class AbstractIndexCompoundType extends AbstractDataModelBase {
+  /**
+   * The name of the compound element.
+   *
+   * @remarks
+   * Extracted from the mandatory 'name' element within the compound XML
+   * structure. Represents the identifier or name of the documented compound
+   * such as a class name, namespace, or filename.
+   */
+  name = ''
+
+  /**
+   * Collection of member data models associated with this compound.
+   *
+   * @remarks
+   * Optional array containing member elements found within the compound
+   * structure. Each member represents a documented entity that belongs
+   * to this compound, such as functions, variables, or other nested
+   * constructs. The array supports zero to many members as per the XML schema.
+   */
+  members: IndexMemberDataModel[] | undefined // [0-n]
+
+  /**
+   * The unique reference identifier for this compound.
+   *
+   * @remarks
+   * Mandatory attribute that provides a unique identifier for referencing
+   * this compound within the Doxygen documentation structure. Used to link
+   * index entries to their detailed definitions in separate XML files.
+   */
+  refid = ''
+
+  /**
+   * The kind classification of this compound.
+   *
+   * @remarks
+   * Mandatory attribute specifying the type of compound (e.g., class, struct,
+   * namespace, file). Corresponds to the CompoundKind enumeration in the
+   * XML schema, determining how the compound should be processed and presented.
+   */
+  kind = '' // CompoundKind
+
+  /**
+   * Constructs a new AbstractIndexCompoundType instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the compound data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * Parses the provided XML element to extract compound information including
+   * the name element, member collections, and mandatory attributes (refid and
+   * kind). The constructor validates that all required data is present and
+   * properly formatted according to the XML schema specifications. Member
+   * elements are processed into IndexMemberDataModel instances when present.
+   */
+  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)
+
+    for (const innerElement of innerElements) {
+      if (xml.hasInnerText(innerElement)) {
+        // Ignore texts.
+      } else if (xml.isInnerElementText(innerElement, 'name')) {
+        assert(this.name.length === 0)
+        this.name = xml.getInnerElementText(innerElement, 'name')
+      } else if (xml.hasInnerElement(innerElement, 'member')) {
+        this.members ??= []
+        this.members.push(new IndexMemberDataModel(xml, innerElement))
+      } else {
+        console.error(util.inspect(innerElement))
+        console.error(
+          `index ${elementName} element:`,
+          Object.keys(innerElement),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    // ------------------------------------------------------------------------
+    // Process attributes.
+
+    assert(xml.hasAttributes(element))
+
+    const attributesNames = xml.getAttributesNames(element)
+    // console.log(attributesNames)
+    for (const attributeName of attributesNames) {
+      // console.log(attributeName)
+      if (attributeName === '@_refid') {
+        this.refid = xml.getAttributeStringValue(element, '@_refid')
+      } else if (attributeName === '@_kind') {
+        this.kind = xml.getAttributeStringValue(element, '@_kind')
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          `index ${elementName} attribute:`,
+          attributeName,
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    assert(this.refid.length > 0)
+    assert(this.kind.length > 0)
+
+    // ------------------------------------------------------------------------
+
+    // console.log(util.inspect(this, { compact: false, depth: 999 }))
+    // console.log('compound: ', this.refid)
+  }
+}
+
+// ----------------------------------------------------------------------------
+
+// <xsd:simpleType name="CompoundKind">
+//   <xsd:restriction base="xsd:string">
+//     <xsd:enumeration value="class"/>
+//     <xsd:enumeration value="struct"/>
+//     <xsd:enumeration value="union"/>
+//     <xsd:enumeration value="interface"/>
+//     <xsd:enumeration value="protocol"/>
+//     <xsd:enumeration value="category"/>
+//     <xsd:enumeration value="exception"/>
+//     <xsd:enumeration value="file"/>
+//     <xsd:enumeration value="namespace"/>
+//     <xsd:enumeration value="group"/>
+//     <xsd:enumeration value="page"/>
+//     <xsd:enumeration value="example"/>
+//     <xsd:enumeration value="dir"/>
+//     <xsd:enumeration value="type"/>
+//     <xsd:enumeration value="concept"/>
+//     <xsd:enumeration value="module"/>
+//   </xsd:restriction>
+// </xsd:simpleType>
+
+/**
+ * Union type representing the various kinds of compounds in Doxygen
+ * documentation.
+ *
+ * @remarks
+ * Corresponds to the CompoundKind simple type in the Doxygen XML schema,
+ * which defines the allowable classifications for documented compounds.
+ * Each value represents a specific type of programming construct or
+ * documentation unit that can be indexed, ranging from code structures
+ * like classes and namespaces to documentation pages and examples.
+ *
+ * @public
+ */
+export type IndexCompoundKind =
+  | 'class'
+  | 'struct'
+  | 'union'
+  | 'interface'
+  | 'protocol'
+  | 'category'
+  | 'exception'
+  | 'file'
+  | 'namespace'
+  | 'group'
+  | 'page'
+  | 'example'
+  | 'dir'
+  | 'type'
+  | 'concept'
+  | 'module'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:element name="compound" type="CompoundType" minOccurs="0" maxOccurs="unbounded"/>
+
+/**
+ * Concrete data model class for index compound elements.
+ *
+ * @remarks
+ * Represents individual compound elements found within Doxygen index XML
+ * structures. This class extends the abstract base to provide specific
+ * handling for 'compound' elements, which reference documented entities
+ * such as classes, namespaces, files, and other structural components
+ * within the indexed documentation. Each compound serves as an entry
+ * point for accessing detailed documentation in separate XML files.
+ *
+ * @public
+ */
+export class IndexCompoundDataModel extends AbstractIndexCompoundType {
+  /**
+   * Constructs a new IndexCompoundDataModel instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the compound data
+   *
+   * @remarks
+   * Initialises the compound data model by parsing the provided XML element
+   * as a 'compound' element type. The constructor delegates to the parent
+   * class for common compound 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, 'compound')
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/doxygen/data-model/index/indexdoxygentype-dm.ts

@@ -0,0 +1,196 @@
+/*
+ * 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 { IndexCompoundDataModel } from './indexcompoundtype-dm.js'
+import { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// WARNING: it clashes with the definition in compound.xsd.
+// <xsd:complexType name="DoxygenType">
+//   <xsd:sequence>
+//     <xsd:element name="compound" type="CompoundType" minOccurs="0" maxOccurs="unbounded"/>
+//   </xsd:sequence>
+//   <xsd:attribute name="version" type="xsd:string" use="required"/>
+//   <xsd:attribute ref="xml:lang" use="required"/>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for Doxygen index type data models.
+ *
+ * @remarks
+ * Represents the top-level structure of Doxygen index XML files, corresponding
+ * to the DoxygenType complex type in the XML schema. This class handles the
+ * parsing of version and language attributes, along with compound element
+ * collections. Note that this definition may clash with similar types in
+ * compound.xsd, requiring careful namespace management.
+ *
+ * @public
+ */
+export abstract class AbstractIndexDoxygenType extends AbstractDataModelBase {
+  /**
+   * The version of the Doxygen tool that generated the XML.
+   *
+   * @remarks
+   * Mandatory attribute extracted from the XML structure that identifies
+   * the version of Doxygen used to generate the documentation. This
+   * information is crucial for compatibility and parsing decisions.
+   */
+  version = ''
+
+  /**
+   * The language specification for the documentation content.
+   *
+   * @remarks
+   * Mandatory attribute corresponding to the xml:lang attribute in the
+   * XML structure. Specifies the primary language used in the documented
+   * content for internationalisation purposes.
+   */
+  lang = ''
+
+  /**
+   * Collection of compound data models referenced in the index.
+   *
+   * @remarks
+   * Optional array containing compound elements found within the index
+   * structure. Each compound represents a documented entity such as
+   * classes, namespaces, or files that are catalogued in the index.
+   */
+  compounds?: IndexCompoundDataModel[] | undefined
+
+  /**
+   * The XML schema location reference for validation.
+   *
+   * @remarks
+   * Optional attribute that specifies the location of the XML schema
+   * definition used for validating the structure of the index XML file.
+   * This provides schema validation capabilities for the parsed content.
+   */
+  noNamespaceSchemaLocation?: string | undefined
+
+  /**
+   * Constructs a new AbstractIndexDoxygenType instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the Doxygen index data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * Parses the provided XML element to extract Doxygen index information
+   * including compound collections and mandatory attributes (version and
+   * language). The constructor validates that all required attributes are
+   * present and processes compound elements into the appropriate data models.
+   * Optional schema location attributes are also extracted when present.
+   */
+  constructor(xml: DoxygenXmlParser, element: object, elementName: string) {
+    super(elementName)
+
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+
+    const innerElements = xml.getInnerElements(element, elementName)
+    assert(innerElements.length > 0)
+
+    for (const innerElement of innerElements) {
+      if (xml.hasInnerText(innerElement)) {
+        // Ignore texts.
+      } else if (xml.hasInnerElement(innerElement, 'compound')) {
+        this.compounds ??= []
+        this.compounds.push(new IndexCompoundDataModel(xml, innerElement))
+      } else {
+        console.error(util.inspect(innerElement))
+        console.error(
+          `index ${elementName} element:`,
+          Object.keys(innerElement),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    // ------------------------------------------------------------------------
+    // Process attributes.
+
+    assert(xml.hasAttributes(element))
+
+    const attributesNames = xml.getAttributesNames(element)
+    // console.log(attributesNames)
+    for (const attributeName of attributesNames) {
+      // console.log(attributeName)
+      if (attributeName === '@_version') {
+        this.version = xml.getAttributeStringValue(element, '@_version')
+      } else if (attributeName === '@_lang') {
+        this.lang = xml.getAttributeStringValue(element, '@_lang')
+      } else if (attributeName === '@_noNamespaceSchemaLocation') {
+        this.noNamespaceSchemaLocation = xml.getAttributeStringValue(
+          element,
+          '@_noNamespaceSchemaLocation'
+        )
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          `index ${elementName} attribute:`,
+          attributeName,
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+    assert(this.version.length > 0)
+    assert(this.lang.length > 0)
+
+    // ------------------------------------------------------------------------
+
+    // console.log(util.inspect(this, { compact: false, depth: 999 }))
+  }
+}
+
+// ----------------------------------------------------------------------------
+
+// <xsd:element name="doxygenindex" type="DoxygenType"/>
+
+/**
+ * Concrete data model class for doxygenindex elements.
+ *
+ * @remarks
+ * Represents the root element of Doxygen index XML files, extending the
+ * abstract base class to provide specific handling for 'doxygenindex'
+ * elements. This class serves as the primary entry point for parsing
+ * index files and provides access to all compound definitions and
+ * metadata contained within the index structure.
+ *
+ * @public
+ */
+export class DoxygenIndexDataModel extends AbstractIndexDoxygenType {
+  /**
+   * Constructs a new DoxygenIndexDataModel instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the doxygenindex data
+   *
+   * @remarks
+   * Initialises the Doxygen index data model by parsing the provided XML
+   * element as a 'doxygenindex' element type. The constructor delegates
+   * to the parent class for common 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, 'doxygenindex')
+  }
+}
+
+// ----------------------------------------------------------------------------

package/src/doxygen/data-model/index/indexmembertype-dm.ts

@@ -0,0 +1,230 @@
+/*
+ * 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 { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="MemberType">
+//   <xsd:sequence>
+//     <xsd:element name="name" type="xsd:string"/>
+//   </xsd:sequence>
+//   <xsd:attribute name="refid" type="xsd:string" use="required"/>
+//   <xsd:attribute name="kind" type="MemberKind" use="required"/>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for index member type data models.
+ *
+ * @remarks
+ * Represents member elements found within Doxygen index XML structures,
+ * corresponding to the MemberType complex type in the XML schema. This
+ * class handles the parsing of member names, reference identifiers, and
+ * member kinds from the XML structure. All concrete member data model
+ * classes should extend this abstract base to ensure consistent parsing
+ * and data representation.
+ *
+ * @public
+ */
+export abstract class AbstractIndexMemberType extends AbstractDataModelBase {
+  /**
+   * The name of the member element.
+   *
+   * @remarks
+   * Extracted from the mandatory 'name' element within the member XML
+   * structure. Represents the identifier or name of the documented member.
+   */
+  name = ''
+
+  /**
+   * The reference identifier for the member.
+   *
+   * @remarks
+   * Mandatory attribute that provides a unique identifier for referencing
+   * this member within the Doxygen documentation structure. Used to link
+   * index entries to their detailed definitions.
+   */
+  refid = ''
+
+  /**
+   * The kind classification of the member.
+   *
+   * @remarks
+   * Mandatory attribute specifying the type of member (e.g., function,
+   * variable, typedef). Corresponds to the MemberKind enumeration in the
+   * XML schema.
+   */
+  kind = '' // MemberKind
+
+  /**
+   * Constructs a new AbstractIndexMemberType instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the member data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * Parses the provided XML element to extract member information including
+   * the name element and mandatory attributes (refid and kind). The constructor
+   * validates that all required data is present and properly formatted
+   * according to the XML schema specifications.
+   */
+  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)
+
+    for (const innerElement of innerElements) {
+      if (xml.hasInnerText(innerElement)) {
+        // Ignore texts.
+      } else if (xml.isInnerElementText(innerElement, 'name')) {
+        assert(this.name.length === 0)
+        this.name = xml.getInnerElementText(innerElement, 'name')
+      } else {
+        console.error(util.inspect(innerElement))
+        console.error(
+          `index ${elementName} element:`,
+          Object.keys(innerElement),
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    // ------------------------------------------------------------------------
+    // Process attributes.
+
+    assert(xml.hasAttributes(element))
+
+    const attributesNames = xml.getAttributesNames(element)
+    // console.log(attributesNames)
+    for (const attributeName of attributesNames) {
+      // console.log(attributeName)
+      if (attributeName === '@_refid') {
+        this.refid = xml.getAttributeStringValue(element, '@_refid')
+      } else if (attributeName === '@_kind') {
+        this.kind = xml.getAttributeStringValue(element, '@_kind')
+      } else {
+        console.error(util.inspect(element, { compact: false, depth: 999 }))
+        console.error(
+          `index ${elementName} attribute:`,
+          attributeName,
+          'not implemented yet in',
+          this.constructor.name
+        )
+      }
+    }
+
+    assert(this.refid.length > 0)
+    assert(this.kind.length > 0)
+
+    // ------------------------------------------------------------------------
+
+    // console.log(util.inspect(this, { compact: false, depth: 999 }))
+  }
+}
+
+// ----------------------------------------------------------------------------
+
+// <xsd:simpleType name="MemberKind">
+//   <xsd:restriction base="xsd:string">
+//     <xsd:enumeration value="define"/>
+//     <xsd:enumeration value="property"/>
+//     <xsd:enumeration value="event"/>
+//     <xsd:enumeration value="variable"/>
+//     <xsd:enumeration value="typedef"/>
+//     <xsd:enumeration value="enum"/>
+//     <xsd:enumeration value="enumvalue"/>
+//     <xsd:enumeration value="function"/>
+//     <xsd:enumeration value="signal"/>
+//     <xsd:enumeration value="prototype"/>
+//     <xsd:enumeration value="friend"/>
+//     <xsd:enumeration value="dcop"/>
+//     <xsd:enumeration value="slot"/>
+//   </xsd:restriction>
+// </xsd:simpleType>
+
+/**
+ * Union type representing the various kinds of members in Doxygen
+ * documentation.
+ *
+ * @remarks
+ * Corresponds to the MemberKind simple type in the Doxygen XML schema,
+ * which defines the allowable classifications for documented members.
+ * Each value represents a specific type of programming construct that
+ * can be documented, ranging from preprocessor definitions to class
+ * methods and properties.
+ *
+ * @public
+ */
+export type IndexMemberKind =
+  | 'define'
+  | 'property'
+  | 'event'
+  | 'variable'
+  | 'typedef'
+  | 'enum'
+  | 'enumvalue'
+  | 'function'
+  | 'signal'
+  | 'prototype'
+  | 'friend'
+  | 'dcop'
+  | 'slot'
+
+// ----------------------------------------------------------------------------
+
+// The name clashes with a similar definition in compound.xsd.
+// <xsd:element name="member" type="MemberType" minOccurs="0" maxOccurs="unbounded" />
+
+/**
+ * Concrete data model class for index member elements.
+ *
+ * @remarks
+ * Represents individual member elements found within Doxygen index XML
+ * structures. This class extends the abstract base to provide specific
+ * handling for 'member' elements, which reference documented members
+ * such as functions, variables, and other programming constructs within
+ * the indexed documentation.
+ *
+ * @public
+ */
+export class IndexMemberDataModel extends AbstractIndexMemberType {
+  /**
+   * Constructs a new IndexMemberDataModel instance from XML data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML elements
+   * @param element - The XML element containing the member data
+   *
+   * @remarks
+   * Initialises the member data model by parsing the provided XML element
+   * as a 'member' element type. The constructor delegates to the parent
+   * class for common member processing whilst specifying the element name.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'member')
+  }
+}
+
+// ----------------------------------------------------------------------------