Commenting Rules & Docstring Standards

To produce accurate code references, UDE relies on structured comments and docstrings within your codebase. This guide details the doc-comment syntax UDE recognizes, the tags it extracts, and exactly how much of the remaining prose is (and isn't) reprocessed before it reaches a rendered page.

---

📑 Supported Docstring Dialects

UDE does not "auto-detect" Javadoc vs. Doxygen as separate styles — @param and \param are treated identically everywhere (see the tag table below). What actually varies is the docstring dialect, selected via the parser.docstring_format config key (default "auto"). The dialect describes a syntax convention for the surrounding docstring, not a 1:1 mapping to source language:

Dialect	Config value	Typical usage	Trigger pattern
Plain	"plain"	C++, C#, and Java by default; universal fallback	Pure passthrough — no dialect-specific extraction beyond the universal tag table below
NumPy	"numpy"	Python SWIG-autodoc bindings	A NumPy-style Parameters / ---------- section and/or a leading autodoc call-signature line, e.g. method(ClassName self, TypeA arg1) -> RetType
Sphinx/RST	"sphinx_rst"	Python SWIG bindings that use Sphinx field lists	:param:, :type:, :rtype:, :return:/:returns:, plus the *Overload N:* multi-overload convention

Since NumPy/Sphinx-RST scoring only ever fires for Python-language SWIG bindings, C++, C#, and Java always effectively use plain in practice — there is no per-language dialect selection UI or mapping.

When docstring_format is left at "auto", UDE samples up to 10 XML files (5 docstrings each) from the target and scores them against the numpy and sphinx_rst patterns. If neither scores above zero, it falls back to numpy for Python or plain for every other language. Passing an unrecognized value raises:

UdeException(f"Unknown docstring_format {spec!r}. Valid values: ['numpy', 'plain', 'sphinx_rst'] or 'auto'.")

Plain dialect

/**
 * \brief Computes the bounding box of a 3D mesh.
 * \param mesh The input mesh model.
 * \param tolerance Precision tolerance factor.
 * \return True if successful, false otherwise.
 */
bool ComputeBounds(const Mesh& mesh, double tolerance);

NumPy dialect (Python SWIG autodoc)

def compute_bounds(mesh, tolerance):
    """
    compute_bounds(mesh, tolerance) -> bool

    Parameters
    ----------
    mesh : Mesh
        The input mesh model.
    tolerance : float
        Precision tolerance factor.
    """

Sphinx/RST dialect (Python SWIG bindings)

def compute_bounds(*args):
    """
    compute_bounds(Mesh mesh, float tolerance) -> bool

    *Overload 1:*
    Computes the bounding box using the default tolerance.

    :param mesh: The input mesh model.
    :type mesh: Mesh
    :return: True if successful, false otherwise.
    :rtype: bool
    """

The *Overload N:* header splits a single SWIG-generated docstring into separate blocks, each rendered as its own #### {method} (Overload {N}) subsection.

:::note Functional Traceability: Docstring dialect selection and parsing traces to REQ-FUN-20: Docstring Normalization Engine. :::

---

🏷️ Recognized Tags

This is the complete set of tags UDE recognizes anywhere in a docstring, regardless of dialect:

Tag(s)	Effect
@param name desc / \param name desc (optional [in]/[out]/[in,out] direction marker)	Removed from prose; becomes that parameter's description
Sphinx :param name: desc	Same as above, Sphinx/RST form
:type name: <type>	Overrides that parameter's displayed type
@return desc / \return desc / @returns desc / \returns desc	Extracted and appended to the method's docstring body as a Returns: section
Sphinx :return: / :returns:	Same as above
:rtype: <type>	Overrides the method's displayed return type when the XML-declared type is absent or generic
@author desc / \author desc	Extracted internally but not currently rendered anywhere — this is a real gap, not a placeholder
@version desc / \version desc	Same — extracted but not currently rendered anywhere
@brief desc / \brief desc	Spliced back in as the first line of the cleaned docstring body — it becomes the lead sentence, not a separate summary field
Google-style Args: / Parameters: section, per-line name (type): desc or name: desc	Parsed into per-parameter description/type, same effect as @param / :type:
Google-style Returns: section	Parsed into the returns metadata
*Overload N:* header (Sphinx/RST dialect only)	Splits the docstring into separate overload blocks (see above)
Sphinx cross-reference roles, e.g. :class:`Foo`, :py:meth:`Bar`	Stripped down to bare text (Foo, Bar) — never turned into a hyperlink
@internal / \internal anywhere in a docstring	The entire class/method/enum/field/variable is silently dropped from the output catalog entirely
DOM-IGNORE-BEGIN...DOM-IGNORE-END, \cond...\endcond / @cond...@endcond	The enclosed block is deleted from the raw XML before parsing even begins

The last two rows are covered in full on the Exclusion Gates page.

Explicitly NOT supported

The following are not recognized anywhere in the engine. If used, they pass through as inert literal text in the rendered docstring body (or are silently ignored if the line isn't otherwise parseable):

• {@link ClassName} Javadoc-style inline links
• @see / \see
• @deprecated
• @since
• @throws / @exception

Do not expect any of these to affect rendering, linking, or filtering — treat them as plain text.

---

🛠️ Parameter Mapping & Types

During tag extraction, UDE separates parameter descriptions from types:

Parameter	Type	Description
mesh	Mesh / const Mesh&	The input mesh model to analyze.
tolerance	double / float	Precision tolerance for calculation.

The displayed type normally comes from the Doxygen XML's declared parameter type. A Sphinx-style :type name: <type> tag overrides that displayed type for the given parameter, and :rtype: <type> overrides the method's displayed return type specifically when the XML-declared return type is absent or generic (e.g. SWIG's typeless Python signatures).

---

🔄 Markdown & Prose Normalization Pipeline

Raw comments go through four real, in-order normalization stages — there is no separate "CommonMark conversion" or "HTML escaping" step at normalization time:

1. Comment-delimiter stripping: removes /**, /*, */, /*!, **/ block delimiters, a leading * per-line marker (but not **), and leading /// or //! line markers. \r\n is normalized to \n first.
2. Plain-text table detection: a bold-header row like **Col1** **Col2** followed by whitespace-column-aligned data rows is rewritten into a real CommonMark pipe table.
3. Tag extraction: the tag table above is applied, with indentation-based multi-line continuation support for multi-line tag values.
4. Whitespace standardization: trims leading/trailing blank lines, dedents by the common minimum indentation, and collapses 3-or-more consecutive blank lines down to exactly one.

There is no fenced-code-block, list, or inline-emphasis re-parsing. Any Markdown formatting (bold, italic, code spans, lists) already present in the source docstring passes through completely untouched as literal text — the engine does not re-parse or re-emit it.

Where Markdown actually becomes HTML

Real Markdown→HTML conversion only happens in the static-HTML renderer family, via the Python markdown library with the tables extension:

markdown.markdown(text, extensions=["tables"])

This runs at render time (via a Jinja2 |markdown filter), not during normalization. If a docstring already looks like raw HTML (starts and ends with angle brackets), it's passed through unchanged.

The Hugo/Docusaurus renderer does not run any Markdown→HTML conversion at all — it emits raw Markdown text and relies on the external Hugo/Docusaurus site build to interpret it. The only thing the Hugo renderer does to prose is escape angle brackets (</> outside of code spans/fences become </>), so raw C++ template syntax like std::vector<T> doesn't get misread as an HTML/MDX tag by the downstream build.

---

🔗 Cross-References, Images & Front Matter

Cross-references

There is no mechanism that turns a textual reference inside docstring prose into a hyperlink. There is no @see support, no {@link} support, and Sphinx cross-reference roles (:class:`Foo`, etc.) are stripped to bare text, never linkified. Do not write @see OtherClass (or similar) in a doc-comment expecting a clickable link — it won't produce one.

The only real hyperlinks UDE generates come from the parsed structure itself, never from docstring prose:

• Nested-class links (Hugo output): a relative path (../../ClassName.md-style, with depth computed from the actual output directory tree), based on the Doxygen refid.
• Namespace/class index-table links (Hugo output): relative, extensionless filenames (.md stripped, lowercased).
• Breadcrumb/namespace links (HTML output): bare filenames only — HTML output is always a flat single directory, so no relative-path computation is needed.
• Inherited members: explicitly NOT linked — rendered as plain text *(inherited from ClassName)*, with ClassName as a literal string in both Hugo and HTML output.

Images

There is no @image/\image Doxygen tag support anywhere in the engine. A Doxygen \image directive produces an XML <image> element with no text content; UDE's docstring extraction only reads .itertext() over paragraph elements, so it silently yields nothing for that element — the image reference is simply lost, never rendered, copied, or path-rewritten.

If a docstring happens to contain literal Markdown image syntax ![alt](path), the static-HTML renderer's markdown library will render an <img> tag from it — but UDE performs no path resolution or rewriting on that path; it's used exactly as written, relative to wherever the output page is served from. There is currently no source-relative image asset pipeline in UDE.

Front matter (Hugo output)

Front matter is hand-built YAML (--- fences), not generated from a schema or library. Exact fields, by page type:

Page type	Fields
Class page	title: "{ClassName} {entity_type}" (e.g. "MyClass class"), sidebar_position: N, optional parent: "{parent}" (only if a non-empty group/namespace parent exists)
Namespace index page (_index.md)	title: "{Namespace} namespace", sidebar_position: 1, description: "Namespace {Namespace} API Reference", optional parent: for nested namespaces
Group/category landing page	title, sidebar_position, description: "List of {group} in {namespace or 'global namespace'}", optional parent
Root/custom page (from sidebar.toml)	title, sidebar_position

No weight, url, or layout front-matter field is ever emitted. sidebar_position is the only ordering key, and page routing is filename/directory-based, not front-matter-driven. A url key does appear in sidebar.toml's own custom-page config schema — but that's the physical output filename to write the page to, not a front-matter field written into the generated page.

---

🏁 Formatting Examples

Raw Input (C++ Header, plain dialect)

/**
 * \brief Normalizes a 3D vector in place.
 * \param vec Vector to modify.
 * \return Reference to the normalized vector.
 * \author J. Smith
 */
Vector3D& Normalize(Vector3D& vec);

Compiled Output (static-HTML renderer)

INFO

Normalizes a 3D vector in place.

Parameters:

• vec (Vector3D&): Vector to modify.

Returns:

Reference to the normalized vector.

Note what's missing: \author J. Smith was extracted during tag parsing but is not rendered anywhere in the output — this is a genuine gap in the current renderers, not an omission in this example.