@xpack/doxygen2docusaurus 1.0.2 → 2.0.0

package/dist/docusaurus/view-model/description-anchors.js

@@ -9,25 +9,83 @@
  * be obtained from https://opensource.org/licenses/MIT.
  */
 // ----------------------------------------------------------------------------
+/**
+ * Represents an anchor within a description section for cross-referencing.
+ *
+ * @remarks
+ * Used to create navigable links within documentation pages, allowing
+ * users to jump to specific sections or content areas within compound
+ * descriptions.
+ *
+ * @public
+ */
 export class DescriptionAnchor {
     compound;
     id;
+    /**
+     * Creates a new description anchor instance.
+     *
+     * @remarks
+     * Associates an anchor identifier with a specific compound to enable
+     * targeted navigation within the documentation structure.
+     *
+     * @param compound - The compound that contains this anchor
+     * @param id - Unique identifier for the anchor
+     */
     constructor(compound, id) {
         this.compound = compound;
         this.id = id;
     }
 }
 // ----------------------------------------------------------------------------
+/**
+ * Manages a table of contents list for a compound's description.
+ *
+ * @remarks
+ * Organises the hierarchical structure of content within a compound
+ * description, providing navigation aids for users browsing complex
+ * documentation sections.
+ *
+ * @public
+ */
 export class DescriptionTocList {
     compound;
     tocItems = [];
+    /**
+     * Creates a new description table of contents list.
+     *
+     * @remarks
+     * Initialises an empty collection of TOC items for the specified
+     * compound, ready to be populated with navigational entries.
+     *
+     * @param compound - The compound that owns this table of contents
+     */
     constructor(compound) {
         this.compound = compound;
     }
 }
+/**
+ * Represents an individual item within a description table of contents.
+ *
+ * @remarks
+ * Each TOC item corresponds to a specific section or anchor within the
+ * compound description, providing structured navigation capabilities.
+ *
+ * @public
+ */
 export class DescriptionTocItem {
     id;
     tocList;
+    /**
+     * Creates a new table of contents item.
+     *
+     * @remarks
+     * Links a specific identifier to its parent TOC list, establishing
+     * the hierarchical relationship between content sections.
+     *
+     * @param id - Unique identifier for this TOC item
+     * @param tocList - The parent table of contents list
+     */
     constructor(id, tocList) {
         this.id = id;
         this.tocList = tocList;

package/dist/docusaurus/view-model/description-anchors.js.map

@@ -1 +1 @@
-{"version":3,"file":"description-anchors.js","sourceRoot":"","sources":["../../../src/docusaurus/view-model/description-anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,+EAA+E;AAE/E,MAAM,OAAO,iBAAiB;IAC5B,QAAQ,CAAc;IACtB,EAAE,CAAQ;IAEV,YAAY,QAAsB,EAAE,EAAU;QAC5C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED,+EAA+E;AAE/E,MAAM,OAAO,kBAAkB;IAC7B,QAAQ,CAAc;IACtB,QAAQ,GAAyB,EAAE,CAAA;IAEnC,YAAY,QAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;CACF;AAED,MAAM,OAAO,kBAAkB;IAC7B,EAAE,CAAQ;IACV,OAAO,CAAoB;IAE3B,YAAY,EAAU,EAAE,OAA2B;QACjD,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;QACZ,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAED,+EAA+E"}
+{"version":3,"file":"description-anchors.js","sourceRoot":"","sources":["../../../src/docusaurus/view-model/description-anchors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAMH,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,OAAO,iBAAiB;IAC5B,QAAQ,CAAc;IACtB,EAAE,CAAQ;IAEV;;;;;;;;;OASG;IACH,YAAY,QAAsB,EAAE,EAAU;QAC5C,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;QACxB,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;IACd,CAAC;CACF;AAED,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAM,OAAO,kBAAkB;IAC7B,QAAQ,CAAc;IACtB,QAAQ,GAAyB,EAAE,CAAA;IAEnC;;;;;;;;OAQG;IACH,YAAY,QAAsB;QAChC,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,OAAO,kBAAkB;IAC7B,EAAE,CAAQ;IACV,OAAO,CAAoB;IAE3B;;;;;;;;;OASG;IACH,YAAY,EAAU,EAAE,OAA2B;QACjD,IAAI,CAAC,EAAE,GAAG,EAAE,CAAA;QACZ,IAAI,CAAC,OAAO,GAAG,OAAO,CAAA;IACxB,CAAC;CACF;AAED,+EAA+E"}

package/dist/docusaurus/view-model/files-and-folders-vm.d.ts

@@ -1,45 +1,292 @@
 import { CompoundBase } from './compound-base-vm.js';
 import type { CompoundDefDataModel } from '../../doxygen/data-model/compounds/compounddef-dm.js';
 import { CollectionBase } from './collection-base.js';
-import type { MenuItem, SidebarCategory, FrontMatter } from '../types.js';
+import type { NavbarItem, SidebarCategory, FrontMatter } from '../types.js';
 import type { Workspace } from '../workspace.js';
 import type { ProgramListingDataModel } from '../../doxygen/data-model/compounds/descriptiontype-dm.js';
+/**
+ * Manages the collection of file and folder documentation compounds.
+ *
+ * @remarks
+ * Handles the organisation and generation of file-based documentation,
+ * including folder hierarchies, file listings, sidebar generation, and
+ * index file creation. Provides a structured view of the source code
+ * organisation with proper navigation support.
+ *
+ * @public
+ */
 export declare class FilesAndFolders extends CollectionBase {
+    /**
+     * Map of folder compounds indexed by identifier.
+     *
+     * @remarks
+     * Stores all folder instances for efficient lookup and hierarchy
+     * construction, separate from the main compounds collection.
+     */
     compoundFoldersById: Map<string, Folder>;
+    /**
+     * Map of file compounds indexed by identifier.
+     *
+     * @remarks
+     * Stores all file instances for efficient lookup and organisation,
+     * separate from the main compounds collection.
+     */
     compoundFilesById: Map<string, File>;
+    /**
+     * Array of top-level folders without parent folders.
+     *
+     * @remarks
+     * Contains folders that are at the root level of the documentation
+     * hierarchy, used for organising hierarchical displays.
+     */
     topLevelFolders: Folder[];
+    /**
+     * Array of top-level files without parent folders.
+     *
+     * @remarks
+     * Contains files that are at the root level of the documentation
+     * hierarchy, not contained within any documented folder.
+     */
     topLevelFiles: File[];
+    /**
+     * Creates a new files and folders collection.
+     *
+     * @remarks
+     * Initialises the collection with separate maps for folders and files
+     * to enable efficient organisation and hierarchy construction.
+     *
+     * @param workspace - The workspace instance
+     */
     constructor(workspace: Workspace);
+    /**
+     * Adds a file or folder compound to the collection.
+     *
+     * @remarks
+     * Creates either a File or Folder instance based on the compound kind,
+     * registers it in the appropriate collections, and returns the created
+     * instance for further processing.
+     *
+     * @param compoundDef - The compound definition for the file or folder
+     * @returns The created File or Folder instance
+     * @throws Error if compound kind is not 'file' or 'dir'
+     */
     addChild(compoundDef: CompoundDefDataModel): CompoundBase;
+    /**
+     * Creates hierarchical relationships between file and folder compounds.
+     *
+     * @remarks
+     * Establishes parent-child relationships for folders and files,
+     * builds the complete file hierarchy, and generates relative paths
+     * and permalinks for all compounds. Registers files in the workspace
+     * for global lookup and identifies top-level entities.
+     */
     createCompoundsHierarchies(): void;
+    /**
+     * Recursively builds the relative path for a folder from root.
+     *
+     * @remarks
+     * Traverses the folder hierarchy upwards to construct the complete
+     * relative path by concatenating parent folder names. Used for
+     * generating proper folder permalinks and navigation structures.
+     *
+     * @param folder - The folder to build the path for
+     * @returns The complete relative path from root to the folder
+     */
     private getRelativePathRecursively;
     addSidebarItems(sidebarCategory: SidebarCategory): void;
+    /**
+     * Creates sidebar items for folder hierarchies recursively.
+     *
+     * @remarks
+     * Generates hierarchical sidebar structures for folder trees,
+     * creating category items with nested children for subfolders
+     * and files. Processes folders first, then files within each
+     * folder level.
+     *
+     * @param folder - The folder to create sidebar items for
+     * @returns The sidebar category item or undefined if folder lacks data
+     */
     private createFolderSidebarItemRecursively;
+    /**
+     * Creates a sidebar document item for a file.
+     *
+     * @remarks
+     * Generates a simple document sidebar item for individual files
+     * with appropriate CSS classes and navigation links. Used for
+     * leaf nodes in the file hierarchy sidebar.
+     *
+     * @param file - The file to create a sidebar item for
+     * @returns The sidebar document item or undefined if file lacks data
+     */
     private createFileSidebarItem;
-    createMenuItems(): MenuItem[];
+    createNavbarItems(): NavbarItem[];
     generateIndexDotMdFile(): Promise<void>;
+    /**
+     * Generates hierarchical index content for folders recursively.
+     *
+     * @remarks
+     * Creates HTML tree table rows for folder hierarchies with proper
+     * indentation and folder icons. Processes subfolders first, then
+     * files within each folder level to maintain organised structure.
+     *
+     * @param folder - The folder to generate index content for
+     * @param depth - The current depth level in the hierarchy (0-based)
+     * @returns Array of HTML strings representing the tree table rows
+     */
     private generateIndexMdFileRecursively;
+    /**
+     * Generates index content for individual files.
+     *
+     * @remarks
+     * Creates HTML tree table rows for file entries with appropriate
+     * file icons, labels, and descriptions. Generates consistent
+     * formatting for file documentation links within hierarchical
+     * index structures.
+     *
+     * @param file - The file to generate index content for
+     * @param depth - The current depth level in the hierarchy (0-based)
+     * @returns Array of HTML strings representing the file table row
+     */
     private generateFileIndexMd;
     isVisibleInSidebar(): boolean;
     generatePerInitialsIndexMdFiles(): Promise<void>;
 }
+/**
+ * Represents a folder compound for directory documentation.
+ *
+ * @remarks
+ * Manages folder-specific functionality including child file and folder
+ * tracking, hierarchy construction, and documentation generation. Provides
+ * structured organisation for file system hierarchies within the
+ * documentation.
+ *
+ * @public
+ */
 export declare class Folder extends CompoundBase {
+    /** Array of child file identifiers contained in this folder. */
     childrenFileIds: string[];
+    /** Array of child folder identifiers contained in this folder. */
     childrenFolderIds: string[];
+    /** Relative path from root to this folder. */
     relativePath: string;
+    /**
+     * Creates a new Folder instance from compound definition data.
+     *
+     * @remarks
+     * Initialises folder metadata including child file and folder
+     * references, display labels, and page titles. Sets up the
+     * folder structure for hierarchy construction and documentation
+     * generation.
+     *
+     * @param collection - The parent FilesAndFolders collection
+     * @param compoundDef - The Doxygen compound definition for the folder
+     */
     constructor(collection: FilesAndFolders, compoundDef: CompoundDefDataModel);
+    /**
+     * Determines if the folder has any children worth displaying.
+     *
+     * @remarks
+     * Recursively checks for files or non-empty subfolders to determine
+     * if the folder should be included in documentation. Empty folders
+     * without content are typically excluded from navigation.
+     *
+     * @returns True if the folder contains files or non-empty subfolders
+     */
     hasChildren(): boolean;
     hasAnyContent(): boolean;
+    /**
+     * Renders the complete folder documentation to markdown lines.
+     *
+     * @remarks
+     * Generates the full documentation page including brief descriptions,
+     * inner directory and file indices, member sections, and detailed
+     * descriptions. Creates structured folder documentation with proper
+     * navigation and content organisation.
+     *
+     * @param frontMatter - The frontmatter configuration for the page
+     * @returns Array of markdown strings representing the complete documentation
+     */
     renderToLines(frontMatter: FrontMatter): string[];
+    /**
+     * Performs late initialisation for folders with content validation.
+     *
+     * @remarks
+     * Validates folder content and conditionally disables sidebar generation for
+     * empty folders. This ensures that folders without meaningful documentation
+     * do not appear in the generated sidebar navigation.
+     *
+     * @public
+     */
     initializeLate(): void;
 }
+/**
+ * Represents a file compound for source code documentation.
+ *
+ * @remarks
+ * Manages file-specific functionality including program listings,
+ * line number tracking, and source code documentation generation.
+ * Provides structured representation of source files within the
+ * documentation hierarchy.
+ *
+ * @public
+ */
 export declare class File extends CompoundBase {
+    /** Relative path from root to this file. */
     relativePath: string;
+    /** Set of line numbers available in the program listing. */
     listingLineNumbers: Set<number>;
+    /** Program listing data for source code display. */
     programListing: ProgramListingDataModel | undefined;
+    /**
+     * Creates a new File instance from compound definition data.
+     *
+     * @remarks
+     * Initialises file metadata including display labels, page titles,
+     * and member sections. Sets up the file structure for documentation
+     * generation and source code listing display.
+     *
+     * @param collection - The parent FilesAndFolders collection
+     * @param compoundDef - The Doxygen compound definition for the file
+     */
     constructor(collection: FilesAndFolders, compoundDef: CompoundDefDataModel);
+    /**
+     * Performs late initialisation for files with program listing setup.
+     *
+     * @remarks
+     * Processes the program listing for source code rendering and tracks valid
+     * line numbers for link validation. Also validates file content and
+     * conditionally disables sidebar generation for empty files.
+     *
+     * @public
+     */
     initializeLate(): void;
+    /**
+     * Determines if the file has any documentable content.
+     *
+     * @remarks
+     * Checks for children elements, inner compounds, and include relationships
+     * to determine content availability. This method helps filter empty files
+     * from the generated documentation.
+     *
+     * @returns True if the file contains documentable content, false otherwise.
+     *
+     * @public
+     */
     hasAnyContent(): boolean;
+    /**
+     * Renders the file documentation to Markdown lines.
+     *
+     * @remarks
+     * Generates comprehensive file documentation including brief description,
+     * includes index, inner compound indices, section indices, detailed
+     * description, and optionally the program listing. The output follows
+     * Docusaurus conventions for file documentation pages.
+     *
+     * @param frontMatter - The front matter configuration for the page
+     * @returns Array of Markdown lines representing the file documentation
+     *
+     * @public
+     */
     renderToLines(frontMatter: FrontMatter): string[];
 }
 //# sourceMappingURL=files-and-folders-vm.d.ts.map

package/dist/docusaurus/view-model/files-and-folders-vm.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"files-and-folders-vm.d.ts","sourceRoot":"","sources":["../../../src/docusaurus/view-model/files-and-folders-vm.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAA;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EACV,QAAQ,EACR,eAAe,EAIf,WAAW,EACZ,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAA;AAQvG,qBAAa,eAAgB,SAAQ,cAAc;IAGjD,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAExC,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAEpC,eAAe,EAAE,MAAM,EAAE,CAAK;IAC9B,aAAa,EAAE,IAAI,EAAE,CAAK;gBAMd,SAAS,EAAE,SAAS;IAUvB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,YAAY;IAoBzD,0BAA0B,IAAI,IAAI;IA6H3C,OAAO,CAAC,0BAA0B;IAYzB,eAAe,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI;IAmHhE,OAAO,CAAC,kCAAkC;IAwC1C,OAAO,CAAC,qBAAqB;IAgBpB,eAAe,IAAI,QAAQ,EAAE;IAUvB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CtD,OAAO,CAAC,8BAA8B;IAsDtC,OAAO,CAAC,mBAAmB;IAiClB,kBAAkB,IAAI,OAAO;IAYvB,+BAA+B,IAAI,OAAO,CAAC,IAAI,CAAC;CAmJhE;AAID,qBAAa,MAAO,SAAQ,YAAY;IACtC,eAAe,EAAE,MAAM,EAAE,CAAK;IAE9B,iBAAiB,EAAE,MAAM,EAAE,CAAK;IAEhC,YAAY,SAAK;gBAIL,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB;IAkC1E,WAAW,IAAI,OAAO;IAYb,aAAa,IAAI,OAAO;IAexB,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;IA0CjD,cAAc,IAAI,IAAI;CAchC;AAID,qBAAa,IAAK,SAAQ,YAAY;IACpC,YAAY,SAAK;IACjB,kBAAkB,cAAoB;IAGtC,cAAc,EAAE,uBAAuB,GAAG,SAAS,CAAA;gBAEvC,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB;IAiBjE,cAAc,IAAI,IAAI;IAiCtB,aAAa,IAAI,OAAO;IA+BxB,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CA6D3D"}
+{"version":3,"file":"files-and-folders-vm.d.ts","sourceRoot":"","sources":["../../../src/docusaurus/view-model/files-and-folders-vm.ts"],"names":[],"mappings":"AAgBA,OAAO,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAA;AACpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sDAAsD,CAAA;AAChG,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAA;AACrD,OAAO,KAAK,EACV,UAAU,EACV,eAAe,EAIf,WAAW,EACZ,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAA;AAEhD,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0DAA0D,CAAA;AAQvG;;;;;;;;;;GAUG;AACH,qBAAa,eAAgB,SAAQ,cAAc;IAGjD;;;;;;OAMG;IACH,mBAAmB,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAExC;;;;;;OAMG;IACH,iBAAiB,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAA;IAEpC;;;;;;OAMG;IACH,eAAe,EAAE,MAAM,EAAE,CAAK;IAE9B;;;;;;OAMG;IACH,aAAa,EAAE,IAAI,EAAE,CAAK;IAM1B;;;;;;;;OAQG;gBACS,SAAS,EAAE,SAAS;IAUhC;;;;;;;;;;;OAWG;IACM,QAAQ,CAAC,WAAW,EAAE,oBAAoB,GAAG,YAAY;IAoBlE;;;;;;;;OAQG;IACM,0BAA0B,IAAI,IAAI;IA6H3C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,0BAA0B;IAYzB,eAAe,CAAC,eAAe,EAAE,eAAe,GAAG,IAAI;IAmHhE;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,kCAAkC;IAwC1C;;;;;;;;;;OAUG;IACH,OAAO,CAAC,qBAAqB;IAgBpB,iBAAiB,IAAI,UAAU,EAAE;IAU3B,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC;IA8CtD;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,8BAA8B;IAsDtC;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,mBAAmB;IAiClB,kBAAkB,IAAI,OAAO;IAYvB,+BAA+B,IAAI,OAAO,CAAC,IAAI,CAAC;CAmJhE;AAID;;;;;;;;;;GAUG;AACH,qBAAa,MAAO,SAAQ,YAAY;IACtC,gEAAgE;IAChE,eAAe,EAAE,MAAM,EAAE,CAAK;IAE9B,kEAAkE;IAClE,iBAAiB,EAAE,MAAM,EAAE,CAAK;IAEhC,8CAA8C;IAC9C,YAAY,SAAK;IAIjB;;;;;;;;;;;OAWG;gBACS,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB;IAkC1E;;;;;;;;;OASG;IACH,WAAW,IAAI,OAAO;IAYb,aAAa,IAAI,OAAO;IAcjC;;;;;;;;;;;OAWG;IAEM,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;IA0C1D;;;;;;;;;OASG;IACM,cAAc,IAAI,IAAI;CAchC;AAID;;;;;;;;;;GAUG;AACH,qBAAa,IAAK,SAAQ,YAAY;IACpC,4CAA4C;IAC5C,YAAY,SAAK;IAEjB,4DAA4D;IAC5D,kBAAkB,cAAoB;IAEtC,oDAAoD;IACpD,cAAc,EAAE,uBAAuB,GAAG,SAAS,CAAA;IAEnD;;;;;;;;;;OAUG;gBACS,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,oBAAoB;IAiB1E;;;;;;;;;OASG;IACM,cAAc,IAAI,IAAI;IAiC/B;;;;;;;;;;;OAWG;IACM,aAAa,IAAI,OAAO;IA8BjC;;;;;;;;;;;;;OAaG;IAEM,aAAa,CAAC,WAAW,EAAE,WAAW,GAAG,MAAM,EAAE;CA6D3D"}