@xpack/doxygen2docusaurus 2.0.0 → 2.1.0

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

@@ -0,0 +1,288 @@
+/*
+ * 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 { RefTextDataModel } from './reftexttype-dm.js'
+import { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="linkedTextType" mixed="true">   <-- Character data is allowed to appear between the child elements!
+//   <xsd:sequence>
+//   <xsd:element name="ref" type="refTextType" minOccurs="0" maxOccurs="unbounded" />
+//   </xsd:sequence>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for linked text elements within documentation content.
+ *
+ * @remarks
+ * Implements processing for linked text elements that contain mixed content
+ * including both textual content and reference elements. This class handles
+ * the XML Schema definition for linkedTextType elements, which support
+ * character data interspersed with reference elements that provide
+ * cross-linking capabilities within documentation structures.
+ *
+ * The implementation processes sequences of text strings and RefTextDataModel
+ * instances, maintaining their original order to preserve the intended
+ * content flow whilst enabling interactive cross-references within the
+ * generated documentation.
+ *
+ * @public
+ */
+export abstract class AbstractLinkedTextType extends AbstractDataModelBase {
+  /**
+   * Constructs an AbstractLinkedTextType instance from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the linked text data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * This constructor processes linked text elements by extracting both
+   * textual content and reference elements in their original order. The
+   * parser maintains the mixed content structure whilst creating appropriate
+   * RefTextDataModel instances for cross-reference elements, ensuring
+   * proper content flow and interactive linking capabilities within the
+   * documentation system.
+   */
+  // Any sequence of them.
+  // children: Array<string | AbstractRefTextType> = []
+
+  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)
+
+    this.children = []
+
+    for (const innerElement of innerElements) {
+      if (xml.hasInnerText(innerElement)) {
+        this.children.push(xml.getInnerText(innerElement))
+      } else if (xml.hasInnerElement(innerElement, 'ref')) {
+        this.children.push(new RefTextDataModel(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="requiresclause" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="initializer" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="type" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="requiresclause" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="initializer" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="exceptions" type="linkedTextType" minOccurs="0" />
+
+// <xsd:element name="initializer" type="linkedTextType" minOccurs="0" />
+
+// <xsd:element name="type" type="linkedTextType" minOccurs="0" />
+
+// <xsd:element name="defval" type="linkedTextType" minOccurs="0" />
+// <xsd:element name="typeconstraint" type="linkedTextType" minOccurs="0" />
+
+/**
+ * Data model for initializer elements within documentation content.
+ *
+ * @remarks
+ * Represents initializer elements that contain variable or member
+ * initialization expressions within source code documentation. This
+ * implementation processes Doxygen's initializer elements, which contain
+ * mixed text and reference content describing the initial values assigned
+ * to variables, constants, or class members.
+ *
+ * The linked text structure enables cross-references to types and symbols
+ * used within initialization expressions.
+ *
+ * @public
+ */
+export class InitializerDataModel extends AbstractLinkedTextType {
+  /**
+   * Constructs an InitializerDataModel from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the initializer data
+   *
+   * @remarks
+   * This constructor delegates to the parent AbstractLinkedTextType to
+   * handle linked text processing whilst identifying the element as
+   * 'initializer' for proper XML schema compliance and initialization
+   * expression content processing.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'initializer')
+  }
+}
+
+/**
+ * Data model for requires clause elements within documentation content.
+ *
+ * @remarks
+ * Represents requires clause elements that contain C++20 concept constraint
+ * expressions within source code documentation. This implementation processes
+ * Doxygen's requiresclause elements, which contain mixed text and reference
+ * content describing the constraints imposed on template parameters and
+ * function arguments via C++20 `requires` clauses.
+ *
+ * The linked text structure enables cross-references to concepts and related
+ * symbols used within requires clause expressions.
+ *
+ * @public
+ */
+export class RequiresClauseDataModel extends AbstractLinkedTextType {
+  /**
+   * Constructs a RequiresClauseDataModel from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the requires clause data
+   *
+   * @remarks
+   * This constructor delegates to the parent AbstractLinkedTextType to
+   * handle linked text processing whilst identifying the element as
+   * 'requiresclause' for proper XML schema compliance and constraint
+   * expression content processing.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'requiresclause')
+  }
+}
+
+/**
+ * Data model for type elements within documentation content.
+ *
+ * @remarks
+ * Represents type elements that contain type information and declarations
+ * within source code documentation. This implementation processes Doxygen's
+ * type elements, which contain mixed text and reference content describing
+ * data types, including primitive types, class names, template parameters,
+ * and complex type expressions.
+ *
+ * The linked text structure enables cross-references to type definitions
+ * and related documentation within the type expressions.
+ *
+ * @public
+ */
+export class TypeDataModel extends AbstractLinkedTextType {
+  /**
+   * Constructs a TypeDataModel from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the type data
+   *
+   * @remarks
+   * This constructor delegates to the parent AbstractLinkedTextType to
+   * handle linked text processing whilst identifying the element as 'type'
+   * for proper XML schema compliance and type information content processing.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'type')
+  }
+}
+
+/**
+ * Data model for default value elements within documentation content.
+ *
+ * @remarks
+ * Represents default value elements that contain parameter default values
+ * within function and method documentation. This implementation processes
+ * Doxygen's defval elements, which contain mixed text and reference content
+ * describing the default values assigned to function parameters when no
+ * explicit value is provided during function calls.
+ *
+ * The linked text structure enables cross-references to constants, enums,
+ * and other symbols used within default value expressions.
+ *
+ * @public
+ */
+export class DefValDataModel extends AbstractLinkedTextType {
+  /**
+   * Constructs a DefValDataModel from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the default value data
+   *
+   * @remarks
+   * This constructor delegates to the parent AbstractLinkedTextType to
+   * handle linked text processing whilst identifying the element as 'defval'
+   * for proper XML schema compliance and default value content processing.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'defval')
+  }
+}
+
+/**
+ * Data model for type constraint elements within documentation content.
+ *
+ * @remarks
+ * Represents type constraint elements that contain template and generic
+ * type constraint information within source code documentation. This
+ * implementation processes Doxygen's typeconstraint elements, which contain
+ * mixed text and reference content describing constraints applied to
+ * template parameters and generic types.
+ *
+ * The linked text structure enables cross-references to constraint types,
+ * concepts, and related template documentation within constraint expressions.
+ *
+ * @public
+ */
+export class TypeConstraintDataModel extends AbstractLinkedTextType {
+  /**
+   * Constructs a TypeConstraintDataModel from XML element data.
+   *
+   * @param xml - The Doxygen XML parser instance for processing XML content
+   * @param element - The XML element object containing the type constraint data
+   *
+   * @remarks
+   * This constructor delegates to the parent AbstractLinkedTextType to
+   * handle linked text processing whilst identifying the element as
+   * 'typeconstraint' for proper XML schema compliance and type constraint
+   * content processing.
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'typeconstraint')
+  }
+}
+
+// ----------------------------------------------------------------------------

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

@@ -0,0 +1,160 @@
+/*
+ * 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 { MemberRefDataModel } from './memberreftype-dm.js'
+import { AbstractDataModelBase } from '../types.js'
+
+// ----------------------------------------------------------------------------
+
+// <xsd:complexType name="listofallmembersType">
+//   <xsd:sequence>
+//     <xsd:element name="member" type="memberRefType" minOccurs="0" maxOccurs="unbounded" />
+//   </xsd:sequence>
+// </xsd:complexType>
+
+/**
+ * Abstract base class for list-of-all-members elements within documentation.
+ *
+ * @remarks
+ * Implements processing for list-of-all-members elements that contain
+ * comprehensive member reference collections within class and compound
+ * documentation. This class handles the XML Schema definition for
+ * listofallmembersType elements, which provide complete inventories of
+ * all members (including inherited members) associated with classes,
+ * structures, and other compound types.
+ *
+ * The implementation processes sequences of member reference elements,
+ * creating MemberRefDataModel instances to maintain detailed information
+ * about each member's identity, scope, and accessibility within the
+ * compound's complete member hierarchy.
+ *
+ * @public
+ */
+// eslint-disable-next-line max-len
+export abstract class AbstractListOfAllMembersType extends AbstractDataModelBase {
+  /**
+   * Collection of member reference elements within the list-of-all-members.
+   *
+   * @remarks
+   * Contains processed member reference data models representing all members
+   * associated with the compound, including both directly declared and
+   * inherited members. Each reference provides comprehensive identification
+   * and scope information for the corresponding member element.
+   *
+   * @public
+   */
+  memberRefs?: MemberRefDataModel[] | undefined
+
+  /**
+   * Constructs a new list-of-all-members data model instance.
+   *
+   * @param xml - The XML parser instance for processing elements
+   * @param element - The source XML element containing list-of-all-members data
+   * @param elementName - The name of the XML element being processed
+   *
+   * @remarks
+   * Processes the XML element to extract and organise member reference
+   * information, creating appropriate data model instances for each
+   * member entry found within the comprehensive member listing.
+   * The constructor validates the element structure and ensures
+   * all member references are properly instantiated.
+   *
+   * @public
+   */
+  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, 'member')) {
+        this.memberRefs ??= []
+        this.memberRefs.push(new MemberRefDataModel(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="listofallmembers" type="listofallmembersType" minOccurs="0" />
+
+/**
+ * Concrete implementation for listofallmembers elements within compound
+ * documentation.
+ *
+ * @remarks
+ * Provides specific handling for listofallmembers XML elements that contain
+ * comprehensive member inventories within class and compound documentation.
+ * This implementation extends the abstract base class functionality to
+ * process the complete collection of member references, including both
+ * directly declared and inherited members.
+ *
+ * The class ensures proper instantiation of member reference data models
+ * whilst maintaining the hierarchical structure and accessibility information
+ * required for comprehensive documentation generation.
+ *
+ * @public
+ */
+export class ListOfAllMembersDataModel extends AbstractListOfAllMembersType {
+  /**
+   * Constructs a new listofallmembers data model instance.
+   *
+   * @param xml - The XML parser instance for processing elements
+   * @param element - The source XML element containing listofallmembers data
+   *
+   * @remarks
+   * Initialises the data model with the specific element name
+   * 'listofallmembers' and delegates processing to the abstract base class
+   * implementation. This ensures consistent handling of member reference
+   * collections whilst maintaining proper element identification.
+   *
+   * @public
+   */
+  constructor(xml: DoxygenXmlParser, element: object) {
+    // console.log(elementName, util.inspect(element, { compact: false, depth: 999 }))
+    super(xml, element, 'listofallmembers')
+  }
+}
+
+// ----------------------------------------------------------------------------