Helveg: Interactive C# Documentation

• Helveg is an interactive tool that redefines API documentation by visualizing C# codebases as unified node-link graphs with details on demand.
• It uses static analysis with MSBuild, NuGet, and Roslyn to extract and abstract code entities, ensuring documentation remains synchronized with the source.
• Its dynamic features, including filtering, zooming, and force-directed layout, support architectural reviews, onboarding, and effective dependency inspection.

Helveg is a prototype tool for software documentation that re-imagines the traditional, text-and-hyperlink API reference as a single interactive node-link diagram. It is designed to analyze C# codebases automatically via static analysis, generate a unified view of project structure and relations, and provide details on demand through filtering, zooming, and inspection panels. Across its initial VISSOFT version and a later extended version, Helveg is presented as an alternative or complement to static textual API documentation, particularly for exploratory analysis of unfamiliar codebases, onboarding, architectural review, and dependency inspection (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

1. Motivation and documentation model

Traditional API reference documentation is described as static text, sometimes accompanied by static UML-style images, and therefore must be read in a predefined order. The papers identify several consequences of this format: difficulty in forming a high-level “mental map” of the entire codebase, difficulty in spotting patterns such as oversized classes, missing abstractions, or hotspots of compiler diagnostics, and difficulty in combining overview-first exploration with drill-down into detail. Even automatically generated API references are characterized as limited to what they can extract from the codebase, cumbersome to navigate, and unable to capture the interwoven nature of code (Štěpánek et al., 14 Jul 2025).

Helveg’s stated objective is to complement or replace a textual API reference with an automatically generated, highly interactive node-link diagram. In the earlier prototype, the emphasis is on a unified, high-level overview of the entire project structure together with “details on demand,” preserved inside a self-contained web application that can be embedded into any website and included in CI/CD documentation builds. In the extended version, the same objective is framed more explicitly as bringing aspects of software architecture visualization to API reference documentation, so that readers can start with a birds-eye view such as “show me all types” and then expand or isolate areas of interest (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

The core documentation model is therefore neither page-centric nor hyperlink-centric. Instead, the codebase itself is treated as a graph-shaped documentation object whose contents are mined automatically from source and rendered as an interactive overview. This suggests a shift from sequential reading to exploratory navigation, while remaining tied to automatically extracted program structure rather than manually maintained narrative text.

2. Static analysis pipeline and entity abstraction

Helveg’s first stage is a console-mode data miner written in C#. It consumes a path to a C# solution file (.sln) and, by driving MSBuild, NuGet, and Roslyn, performs project resolution, semantic model extraction, entity abstraction, and JSON serialization. MSBuild and NuGet identify all projects, source files, and package dependencies in the solution, guaranteeing no circular dependencies. Roslyn parses syntax trees and builds semantic symbol tables, from which Helveg constructs an internal entity abstraction (Štěpánek et al., 2024).

In both papers, the “Entity” model is the central intermediate representation. Every code element becomes an entity with metadata. The earlier paper states that each entity receives a unique hierarchical token, defined as a sequence of integers encoding the path from the solution root, which avoids cycles even with overloaded or generic methods. The reported entity kinds include solution, project, namespace, type, method, field, property, and event; the extended version refines the type and method categories with examples such as class, struct, interface, enum, delegate, and constructor, getter, or operator. Additional metadata include accessibility, static-modifier flag, member counts, Roslyn diagnostics, and XML documentation comments (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

The pipeline terminates in serialization of the entire entity graph and its relations into a single JSON bundle. In the extended version, this serialized output is paired with configuration and presets, including colors, which relations to show, and layout parameters, emitted as JSON alongside HTML/CSS/JS. The result is a documentation artifact generated directly from the buildable codebase rather than manually authored pages, with the stated consequence that it does not drift out of sync (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

3. Graph representation and visual encoding

The earlier paper gives a formal graph model. Helveg represents the codebase as a directed, labeled graph $G = (V,E)$, where $V$ is the set of all entities and $E$ is the union of multiple relation subsets. The primary relation is $\mathrm{declares} \subseteq V \times V$, representing the containment hierarchy from solution to project, namespace, type, and member. Additional relations include $\mathrm{inheritsFrom}$, $\mathrm{typeOf}$, $\mathrm{dependsOn}$, and $\mathrm{invokes}$, the last described as applicable if body analysis were enabled. The extended paper does not give a formal mathematical model, but it retains the same graph-centered architecture and adds further relation examples such as returnType and parameterType (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

The node glyph design changed substantially between versions. In the original prototype, nodes are compound glyphs in which a circular outline encodes static versus non-static modifier and counts of static and non-static members: an innermost outline distinguishes static (dashed) from non-static (solid), the middle solid stroke width is proportional to the number of non-static members, and the outer dashed stroke width is proportional to the number of static members. The circle’s area is scaled by an entity-kind base radius plus a function of member count, with user-selectable linear, logarithmic, or square-root scaling. The center contains the Visual Studio icon for the entity kind, with a small corner icon for non-public accessibility. Nodes with compiler errors emit fire, and nodes with warnings emit smoke (Štěpánek et al., 2024).

The extended version replaces concentric outlines with donut charts, redesigns all 98 icons, and adds explicit polygonal contours for abstract and sealed entities. All glyphs remain circular. The central icon, stroked or filled, encodes entity kind and static modifier; static is indicated by a filled icon and instance by a stroked icon. Accessibility is still represented by a small corner icon. For types, aggregated data are represented by a donut chart with up to two sectors, where the filled sector corresponds to static-member ratio, the cross-hatched sector to instance-member ratio, and donut width is proportional to total member count. Diagnostics remain visually prominent: fire animation for error, smoke for warning, and an upper-left icon for descendant diagnostics in the subtree (Štěpánek et al., 14 Jul 2025).

The extended paper also summarizes the radius calculation as

$$r_{\mathrm{entity}} = r_0(\mathrm{kind}) + \alpha \cdot \mathrm{height}(\mathrm{subtree}) + \beta \cdot |\mathrm{members}|$$

and

$$r_{\mathrm{rendered}} = \mathrm{scale}(r_{\mathrm{entity}})$$

where $V$0 is chosen by the user from $V$1. This makes explicit that node size is intended to encode both local and aggregated structure (Štěpánek et al., 14 Jul 2025).

4. Layout, interaction, and filtering

Helveg combines hierarchical and force-directed layout. The initial structure is arranged with Reingold–Tilford, called TidyTree in the prototype and “TidierTree” in the extended paper, applied to the declares tree. The earlier paper describes this as assigning each subtree of $V$2 to a radial dendrogram instantly. ForceAtlas2 is then used for flexible force-directed refinement so that non-tree relations such as inheritsFrom and typeOf can attract or repel. In the prototype, refinement iterates until convergence or until the user pauses it; in the extended version, it can auto-stop when average node traction $V$3 drops below a configurable threshold $V$4 (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

Interactivity is organized around focus+context operations. In the prototype, users can click to expand a namespace, double-click to collapse a type, highlight matches by rendering non-matching nodes in gray, or isolate matches by removing non-matching nodes entirely. The extended version preserves expand/collapse and isolate behavior while adding a more conventional command surface: shift+drag or arrow keys for manual repositioning, a context menu and keyboard shortcuts for expand, collapse, isolate node, remove branch, run layout, and show inspector, and a synchronized Tree View pane (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

Filtering evolved from three modes to four. The prototype supports full-text search on entity names, regular-expression search on names, and a custom JavaScript mode in which the user writes a predicate over metadata fields such as diagnostics, member count, or XML comments. The extended version retains these and adds a filter builder UI with property, operator, and value choices chained by logical AND. Example selectable properties include kind, accessibility, diagnosticsCount, and hasXmlDocs; example operators include =, ≠, <, >, and contains (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

Details on demand are provided by an inspector side panel. In the prototype it shows entity name, kind, accessibility, static flag, full member list with signatures and return types, Roslyn diagnostics, XML documentation comments, and outgoing and incoming edges by relation category. In the extended version it is described as showing the entity’s declaration, XML doc comments, compiler diagnostics, and a live preview of its glyph. These features situate the diagram as both overview and navigable documentation surface rather than merely a visualization layer (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

5. Implementation, deployment, and observed performance

Helveg’s implementation is split between a back-end data miner and a browser-based diagram UI. The data miner is a C# console application using Microsoft.Build.MSBuild APIs, a NuGet packages resolver, and Roslyn’s SyntaxTree and SemanticModel APIs. The diagram UI uses Svelte for the user interface, Graphology for graph abstractions or graph data structure management, Sigma.js with WebGL for rendering, and D3 for charts such as donut glyphs. The prototype further notes custom shaders for glyphs and animated effects (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

Deployment is explicitly static. Helveg produces either a multi-file static web app or a single self-contained HTML file, suitable for embedding in any documentation site without server dependencies. The extended paper describes a typical workflow in which the tool is installed via .NET tool, invoked after dotnet build, and configured with options such as --relations declares,inheritsFrom,typeOf, --layout.scale log, and --layout.forceAtlas2.stopThreshold 0.05. The generated output can be committed or hosted alongside DocFx or Sphinx API pages, and embedded through a link or an iframe. Configuration can also be captured in helveg.json for reuse (Štěpánek et al., 14 Jul 2025).

The prototype reports performance observations on an 8-project, approximately 3,760-node solution. Data mining completes in seconds on a typical developer machine; TidyTree layout is instantaneous, reported as less than 100 ms; and the ForceAtlas2 pass depends on node count and enabled relations, with 1,000–3,000 nodes converging in 1–5 s while the UI remains responsive to user panning and zooming during iteration. The later paper identifies scalability as a limitation for very large solutions, especially with hundreds of projects and tens of thousands of types, where both performance and visual clutter degrade (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).

6. Evaluation and redesign trajectory

The first evaluation was a formative user study with five professional C# developers, each with 5+ years of experience, organized as 45-minute sessions with no prior Helveg training beyond the statement of purpose “explore an unfamiliar codebase via interactive diagrams.” Tasks included identifying the most important projects in a KAFE solution diagram, discovering external dependencies between projects and NuGet packages, locating code issues via compiler diagnostics and “code smells,” and experimentally comparing two versions of KAFE via an overlay diff. A post-task Likert questionnaire used a 1–5 scale for visual clarity, interactivity, performance, intuitiveness, and overall usefulness (Štěpánek et al., 2024).

The extended evaluation reused the same group of participants, now described as five professional C# developers with 7–12 yrs experience. Round 1 covered the original prototype with open-ended exploratory tasks and a glyph-recognition survey. Round 2 evaluated the redesigned system through seven focused tasks on new features, followed by Likert-scale questionnaires on Readability, Interactivity, UI Design, and Intuitiveness, together with a glyph-recall test (Štěpánek et al., 14 Jul 2025).

The first study reported that all participants quickly located architectural hotspots such as oversized classes and entry-point projects, and that the compiler-diagnostic fire and smoke animations were universally praised as an immediately visible health-check layer. Performance was deemed better than heavy IDE diagrams such as Visual Studio’s Code Map. At the same time, the customizable Visual Studio glyphs felt “familiar,” but participants still needed a brief tutorial to understand outline widths and corner icons, and the JavaScript filter mode was considered powerful but uncomfortable. All five developers stated that they would use Helveg for onboarding new teammates, architectural reviews, or as a replacement for current dependency-analysis tooling (Štěpánek et al., 2024).

The redesign addressed precisely those weaknesses. The cumbersome toolbox was replaced by a traditional toolbar, mnemonic keyboard shortcuts, context menus, an interactive tutorial, a cheat sheet button, inline hints, a Tree View pane, a filter builder UI, redesigned glyphs, and auto-stopping ForceAtlas2 refinement after expand/collapse. The second study reports approximate mean Likert-score improvements as follows (Štěpánek et al., 14 Jul 2025):

Dimension	Study 1 Mean	Study 2 Mean
Readability	3.3	3.9
Interactivity	2.8	4.2
UI Design	2.9	4.1
Intuitiveness	2.6	4.0

After Round 2, glyph recall is reported as approximately $V$5 correct for icon-to-kind assignment and approximately $V$6 correct for composite glyph interpretation (Štěpánek et al., 14 Jul 2025). Taken together, the two studies indicate that Helveg’s central premise—an automatically generated interactive diagram as software documentation—was supported by practitioners, while readability, intuitiveness, and user experience required significant redesign.

7. Limitations and future directions

The extended paper identifies three primary limitations. First, scalability remains problematic: performance and visual clutter degrade on very large solutions, and filtering mitigates but does not fully solve the issue. Second, layout speed can be slow during force-directed convergence, and moving nodes under the cursor can be distracting. Third, configuration complexity can overwhelm new users, although tutorial mechanisms partly address this (Štěpánek et al., 14 Jul 2025).

Future enhancements are listed in several directions. For overview design, the paper proposes alternative representations such as hybrid node-link plus circular treemap, clustering, and aggregation. For rendering, it proposes offloading to WebGPU for higher throughput. For analysis depth, it proposes method-body call graphs, constant-value flows, and maintainability metrics. For longitudinal comparison, it proposes a diffing mode to visualize structural differences between API versions. For ecosystem integration, it proposes editor and platform plugins for VS Code, Rider, and GitHub Pages, together with live sync. It also calls for broader user studies with larger and more diverse developer populations (Štěpánek et al., 14 Jul 2025).

Within the boundaries stated by the papers, Helveg is therefore best understood as a research prototype in interactive software documentation: one that demonstrates a viable, insight-rich alternative to classical API references for C# codebases, while still confronting open problems of scale, layout behavior, and interaction design (Štěpánek et al., 2024, Štěpánek et al., 14 Jul 2025).