---
title: 'HGEN: Hierarchical Documentation Generator'
url: https://www.emergentmind.com/topics/hgen
type: topic
---

# HGEN: Hierarchical Documentation Generator

Searching arXiv for the relevant HGEN papers to ground the article in the current literature.
HGEN, short for Hierarchical GENerator, is a fully automated pipeline for software maintenance that leverages large language models to transform source code into a well-organized hierarchy of formatted documents and associated traceability links. Its central objective is to automate the creation of multi-level software documentation for code bases in which manual documentation is incomplete, costly to maintain, or absent. In the reported formulation, HGEN incrementally converts source code into structured natural-language artifacts, dynamically constructs document hierarchies, and links documentation nodes to repository files, thereby supporting code comprehension, onboarding, and maintenance workflows [2408.05829].

## 1. Definition and research context

HGEN was introduced to address a persistent software-engineering problem: creating and maintaining high-quality, multi-level documentation is time-consuming, so many repositories lack adequate documentation. The framework positions documentation generation as a hierarchical synthesis problem rather than a one-shot summarization task. Instead of producing a flat repository summary, it constructs what the authors describe as an artifact tree, in which lower-level source representations are clustered, abstracted, refined, and connected into higher-level artifacts such as user stories, requirements, or comparable stakeholder-facing documents [2408.05829].

This hierarchical orientation also defines HGEN’s role within later repository-summarization work. A subsequent study characterizes HGEN as a multi-stage LLM framework for repository-level documentation generation and traceability link creation, and treats it as the state-of-the-art baseline prior to RepoSummary. In that characterization, HGEN summarizes repository content hierarchically, builds document structure dynamically, and provides traceability at the file level, but not at the method level [2510.11039].

## 2. Pipeline architecture and hierarchy construction

The HGEN pipeline is described as transforming source code through a series of stages into progressively more abstract documentation. The detailed exposition includes Stage 0 code summarization as preprocessing, followed by clustering, generation, refinement, trace-link generation, duplicate detection, and recursive reuse of the generated layer as input to the next abstraction level [2408.05829].

| Phase | Function | Main techniques |
|---|---|---|
| Code summarization | Convert source files into concise natural-language artifacts | Claude 2.0 |
| Clustering | Group related lower-level artifacts for higher-level abstraction | Sentence-BERT; OPTICS, Spectral, Agglomerative, Affinity Propagation, K-means |
| Documentation generation | Produce higher-level artifacts per cluster | Claude 2.0 with stakeholder-specified or LLM-generated formats |
| Refinement and deduplication | Reduce overlap and sharpen artifact focus | Reclustering and LLM regeneration |
| Intra-layer trace linking | Connect higher-level and lower-level artifacts | Embedding similarity with min-max scaling |
| Inter-cluster duplicate detection | Merge or share links across semantically redundant artifacts | Pairwise cosine similarity |
| Recursive application | Build deeper hierarchy levels | Reuse generated layer as new input |

The initial preprocessing stage turns raw code into concise summaries intended to increase information density for subsequent LLM processing. Clustering then groups related artifacts using Sentence-BERT embeddings and five candidate clustering algorithms: OPTICS, Spectral, Agglomerative, Affinity Propagation, and K-means. Clusters are ranked by an importance score,
\[
\text{importance} = (\alpha \cdot \log s + h) \cdot v
\]
where \(s\) is cluster size, \(h\) is cohesion, and \(v\) is the voting count across clustering methods. Cohesion is defined as
\[
\text{cohesion} = \frac{2}{N(N-1)} \sum_{i=1}^N\sum_{j=1, j \neq i}^N \cos(\theta_{ij}).
\]
Artifacts identified as outliers are removed using a 1.5 SD threshold on similarity, and orphans are attached to the most similar cluster when appropriate [2408.05829].

For higher-level generation, HGEN estimates the number of target artifacts in a cluster using
\[
n_{\text{targets}} = \text{concept\_diversity} \times \text{information\_density},
\]
with concept diversity defined as the inverse of cohesion after normalization, and information density defined as the total size of cluster artifacts divided by the average artifact size of the type. The resulting value is truncated and limited to between 50% and 100% of the cluster’s artifact count. This stage uses Claude 2.0 to produce stakeholder-oriented artifacts in the requested format [2408.05829].

## 3. Language-model integration and traceability mechanisms

Large language models are central to HGEN’s operation. Claude 2.0 is used in code summarization, higher-level artifact generation, and refinement. The architecture is described as model-agnostic, but the implementation emphasizes Claude 2.0 because of its large context window and output quality. Embedding-based operations are delegated to Sentence-BERT, which supplies the semantic representation used for clustering and for trace-link scoring [2408.05829].

Traceability is generated dynamically rather than being assumed from directory structure. For intra-cluster trace linking, HGEN computes min-max scaled cosine similarity between higher-layer and lower-layer artifacts and creates links for pairs within two standard deviations of the maximum similarity, with a typical cutoff of approximately 0.8. If a lower-level artifact has no strong match, it is linked to the closest higher-level artifact to guarantee coverage. A later stage performs pairwise similarity across all higher-level artifacts, marks pairs more than two standard deviations above the mean as potential duplicates, and shares or merges trace links when two artifacts are both highly similar and related to the same lower-level artifacts. If two artifacts have identical trace links, one is removed as a redundant duplicate [2408.05829].

This design yields a hierarchy whose parent-child relations are induced from semantic similarity and subsequent refinement, rather than from package boundaries alone. A plausible implication is that HGEN treats documentation as a latent conceptual structure recoverable from source-level semantic regularities, with LLMs generating the linguistic realization and embedding models enforcing structural consistency.

## 4. Empirical evaluation and reported performance

HGEN was evaluated in two settings: a controlled academic study and industrial pilot deployments. The academic study used three real-world projects with existing documentation and domain experts: Dronology, SAFA, and Jack of Clubs. The industrial study comprised nine pilots at seven companies across eight unique projects, including enterprise, automotive, SaaS, IT, aerospace, and education contexts, and repositories in C#, Java, TypeScript, C/C++, and Go [2408.05829].

In the academic study, experts compared HGEN-generated artifacts, a baseline LLM approach without clustering or refinement, and manually crafted documentation. Artifacts were scored on readability, appropriateness, conciseness, importance, usefulness, and helpfulness. HGEN significantly outperformed manual documentation in readability, appropriateness, usefulness, and helpfulness, with mean scores of 4.38 versus 3.9 for readability, 4.16 versus 3.70 for appropriateness, 4.14 versus 3.51 for usefulness, and 4.21 versus 3.82 for helpfulness, with \(p < 0.05\) under Mann–Whitney U testing. The baseline and manual documentation were otherwise broadly comparable, although HGEN was preferred over the baseline on usefulness [2408.05829].

Coverage results emphasize the contribution of the hierarchical pipeline. Relative to the baseline LLM approach, HGEN achieved dramatically higher core-concept coverage: 87.5% versus 6.3% on Dronology, 84.4% versus 37.8% on SAFA, and 100% versus 50% on Jack of Clubs. Relationship quality also improved. For Dronology, HGEN achieved mAP 94.0, precision 56.3, recall 93.4, and 0 orphans, compared with 84.5, 47.2, 89.5, and 17 for the baseline. For SAFA, the corresponding results were 94.5, 54.3, 98.4, and 9 versus 91.9, 49.2, 100, and 28. For Jack of Clubs, they were 96.7, 81.4, 80.2, and 1 versus 95.5, 67.3, 74.5, and 11 [2408.05829].

Industrial feedback was qualitative rather than metric-driven. Stakeholders emphasized documentation quality, clarity of hierarchical structure, and utility for system comprehension, onboarding, and regulatory compliance. The paper also reports that stakeholder feedback highlighted HGEN’s commercial impact potential as a tool for accelerating code comprehension and maintenance tasks [2408.05829].

## 5. Subsequent comparative assessments

Later work used HGEN as the principal baseline for repository summarization and documentation generation with traceability. In that comparison, HGEN is described as incrementally converting source code into well-structured documentation, dynamically constructing document hierarchies, and generating file-level traceability links from documentation segments to repository files. The same study states that HGEN does not support method-level traceability and evaluates it with advanced LLMs such as GPT-4o mini and Claude 3 [2510.11039].

The comparison reports feature-coverage metrics using \(Q_{\text{Manual}}\) for ground-truth manual features and \(Q_{\text{Generated}}\) for generated features. Averaged over repositories and models, HGEN with GPT-4o mini achieved \(C = 1.00\), \(CB = 0.611\), and \(CC = 0.612\), where \(C\) is Covered, \(CB\) is Covered by, and \(CC\) is Completely Covered. On file-level traceability over three repositories with GPT-4o mini, HGEN achieved precision 0.306, recall 0.299, and F1 0.308. RepoSummary improved completely covered features by 0.099 and file-level recall by 0.231, and was described as more conceptually consistent, easier to understand, and better formatted [2510.11039].

These later findings do not negate HGEN’s contributions; rather, they delimit its operating assumptions. The reported weaknesses are tied to file-level summarization granularity and the absence of method-level traceability. This suggests that HGEN’s hierarchy-generation mechanism is effective for repository-scale abstraction, but can miss feature boundaries that span multiple files or methods when those boundaries are not well aligned with file-level summaries.

## 6. Limitations, practical significance, and future directions

HGEN’s reported limitations are structural rather than merely lexical. Some stakeholders disagreed with automatically inferred artifact hierarchies relative to their own project-specific conceptual models. The system may miss documentation relevant to external APIs or libraries when the necessary context is not present directly in the code base. The effectiveness of the approach also depends partly on the choice of LLM and embedding model, even though the architecture is presented as modular [2408.05829].

At the same time, the practical significance of HGEN lies in its coupling of abstraction, formatting, and traceability. The framework does not simply summarize files; it attempts to recover a navigable documentation hierarchy with meaningful dependencies between levels. In industrial pilots, this hierarchical structure was valued for providing “summary at every level of depth,” particularly for legacy or poorly documented systems, and for supporting onboarding and compliance-oriented workflows [2408.05829].

The future directions reported for HGEN include longitudinal deployment in live documentation workflows, integration of external knowledge sources such as libraries and design documents, greater configurability for different lifecycle models and artifact types, and incremental or “just-in-time” documentation generation as code evolves [2408.05829]. A plausible implication is that HGEN occupies an important transitional point in repository intelligence: it established hierarchical, LLM-centered documentation generation as a viable maintenance workflow, and subsequent systems extended that line by pushing toward finer-grained feature decomposition and richer traceability semantics [2510.11039].

Source: https://www.emergentmind.com/topics/hgen