feat(metadata): support recursive inline elements in documentation

Author: alandefreitas

.github/workflows/ci.yml

@@ -497,6 +497,71 @@ jobs:
           # The schema in the docs folder is valid
           npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
 
+      - name: Verify snippet .cpp files match golden tests (bash)
+        shell: bash
+        run: |
+          set -euo pipefail
+          shopt -s nullglob
+          
+          SRC="docs/website/snippets"
+          DST="test-files/golden-tests/snippets"
+          
+          [[ -d "$SRC" ]] || { echo "Source directory not found: $SRC"; exit 2; }
+          [[ -d "$DST" ]] || { echo "Destination directory not found: $DST"; exit 2; }
+          
+          missing=()
+          mismatched=()
+          
+          # Walk all .cpp files under SRC
+          while IFS= read -r -d '' src; do
+            rel="${src#$SRC/}"
+            dst="$DST/$rel"
+          
+            if [[ ! -f "$dst" ]]; then
+              missing+=("$rel")
+              continue
+            fi
+          
+            if [[ "${STRICT_EOL:-0}" == "1" ]]; then
+              # strict byte-for-byte comparison
+              if ! cmp -s -- "$src" "$dst"; then
+                mismatched+=("$rel")
+              fi
+            else
+              # ignore CRLF/LF differences using git diff (available on all runners)
+              if ! git diff --no-index --ignore-cr-at-eol --quiet -- "$src" "$dst"; then
+                mismatched+=("$rel")
+              fi
+            fi
+          done < <(find "$SRC" -type f -name '*.cpp' -print0)
+          
+          if (( ${#missing[@]} || ${#mismatched[@]} )); then
+            if (( ${#missing[@]} )); then
+              echo "Missing corresponding golden files:"
+              printf '  %s\n' "${missing[@]}"
+            fi
+            if (( ${#mismatched[@]} )); then
+              echo "Content mismatches:"
+              printf '  %s\n' "${mismatched[@]}"
+            fi
+            exit 1
+          fi
+          
+          echo "All snippet .cpp files are present and match."
+        env:
+          # Set to "1" to enforce byte-for-byte equality (do not ignore CRLF/LF)
+          STRICT_EOL: "0"
+
+
+      - name: Check landing page snippets
+        run: |
+          # Find python
+          python=$(command -v python3 || command -v python)
+          # The schema in this branch is up to date 
+          "$python" ./util/generate-yaml-schema.py --check
+          # The schema in the docs folder is valid
+          npx -y -p ajv-cli -- ajv compile -s docs/mrdocs.schema.json
+
       - name: Upload GitHub Release Artifacts
         if: ${{ matrix.is-main && matrix.compiler != 'clang' }}
         uses: actions/upload-artifact@v4

docs/modules/ROOT/pages/commands.adoc

@@ -1,6 +1,6 @@
 = Commands
 
-The code should be documented with the https://docs.oracle.com/en/java/javase/13/docs/specs/javadoc/doc-comment-spec.html[Doc Comment,window=_blank] format, also informally known as "javadoc" format or Doxygen-style comments.
+The code should be documented with the https://docs.oracle.com/en/java/javase/13/docs/specs/javadoc/doc-comment-spec.html[Doc Comment,window=_blank] format, also informally known as Javadoc-style or Doxygen-style comments.
 
 In its most basic form, these are usually comment blocks between `pass:[/**]` and `pass:[*/]` placed above a class, function, or field declaration:
 
@@ -43,6 +43,64 @@ Most doc comments will contain these two sections, which could also be explicitl
 Doc comments can also contain many special commands, such as `@param`, that are used to document the parameters of a function.
 Mr. Docs supports most commands commonly used in Javadoc and Doxygen comments.
 
+== Documentation Comment Formats
+
+The documentation format used by MrDocs has its roots in earlier tools and languages. It is based on writing structured comments directly in the source code, which are then parsed to generate API reference documentation.
+
+* **Origins: Javadoc**: The format originated with Java and the `doc` tool.
+The https://docs.oracle.com/en/java/javase/17/docs/specs/doc/doc-comment-spec.html[official specification] consistently calls these comments *Documentation Comments*, often abbreviated as "doc comments". In practice, many developers also refer to them as *Javadoc-style comments* due to their close association with the `doc` tool.
+* **Doxygen**: When Doxygen was created to support C, C++, and other languages, it adopted a similar comment style. In its https://www.doxygen.nl/manual/docblocks.html[documentation section about this comment style], Doxygen calls these comments *comment blocks*, but also explains them as *Javadoc style comments* for users familiar with the Java ecosystem. This established the convention of using the same recognizable syntax (`/** ... */`) across different ecosystems.
+* **JSDoc**: For JavaScript, the https://jsdoc.app/[JSDoc] tool introduced the same concept. Developers usually refer to them as *JSDoc comments*, again following the tradition of naming the comments after the tool.
+
+Other ecosystems have adopted similar approaches and comment styles, sometimes with different syntax:
+
+- C#: XML documentation comments (`/// ...`)
+- Rust: doc comments (`/// ...` and `//! ...`)
+- Swift: markup-based documentation comments (`/// ...`)
+
+[cols="1,1,2,2",options="header"]
+|===
+| Language | Tool | Official Term | Common Term
+
+| Java
+| Javadoc
+| https://docs.oracle.com/en/java/javase/17/docs/specs/doc/doc-comment-spec.html[Documentation comments]
+| Javadoc-style comments
+
+| C, C++, etc.
+| Doxygen
+| https://www.doxygen.nl/manual/docblocks.html[Comment blocks]
+| Doxygen-style comments
+
+| JavaScript
+| JSDoc
+| https://jsdoc.app/[JSDoc comments]
+| -
+
+| C#
+| XML Documentation Comments
+| https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/[XML documentation comments]
+| -
+
+| Rust
+| Rustdoc
+| https://doc.rust-lang.org/rustdoc/the-doc-attribute.html[Doc comments]
+| -
+
+| Swift
+| Swift Markup
+| https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/[Markup documentation comments]
+| -
+|===
+
+Briefly summarizing the table above:
+
+- The original term, from Java, is *doc comments*. Other tools follow a similar convention.
+- Many tools and communities prefer to call them after the tool name, e.g. *Javadoc-style comments*, *Doxygen-style comments*, or *JSDoc-style comments*.
+- MrDocs follows this tradition by supporting a familiar syntax that developers across ecosystems already recognize.
+
+
+
 // == Style
 //
 // The following commands can be used to format the text in the doc comments:

docs/modules/ROOT/pages/contribute.adoc

@@ -49,7 +49,7 @@ As a last step, `DoGenerateAction` converts the public `Config` settings into a
 [#representing_symbols]
 == Representing Symbols
 
-MrDocs has many categories of objects, where we utilize polymorphism with a fixed set of valid derived types, including Symbols (functions, classes, and enums), Javadoc blocks, template parameters, template arguments, and data types. For each such family, we follow a consistent file layout. Most of these families are defined in the `mrdocs/Metadata` directory.
+MrDocs has many categories of objects, where we utilize polymorphism with a fixed set of valid derived types, including Symbols (functions, classes, and enums), DocComment blocks, template parameters, template arguments, and data types. For each such family, we follow a consistent file layout. Most of these families are defined in the `mrdocs/Metadata` directory.
 
 Each base class is defined in its own header and, when necessary, implementation file. Each derived class also has its own header and implementation file. Finally, there is a single aggregator header file that includes all the derived headers. This file centralizes logic that requires knowledge of the full set of variants, such as visitors, comparison operators, and other operations that depend on the discriminator.
 
@@ -144,7 +144,7 @@ are merged into a map containing the merged results from all other TUs.
 The merging step is necessary as there may be multiple identical definitions of the same entity.
 For instance, this represents the case where a function is declared at different points in the code base and might have different attributes or comments.
 At this step, the doc comments are also finalized.
-Each `Symbol` object has a pointer to its `Javadoc`  object (`mrdocs/Metadata/Javadoc.hpp`), which is a representation of the documentation comments.
+Each `Symbol` object has a pointer to its `DocComment`  object (`mrdocs/Metadata/DocComment.hpp`), which is a representation of the documentation comments.
 
 After AST traversal and `Symbol` merging, the result is stored as a map of `Symbol` objects indexed by their respective `SymbolID`.
 A second finalization step is then performed in `mrdocs::finalize`, where any references to `SymbolID` objects that don't exist are removed.

docs/modules/ROOT/pages/index.adoc

@@ -1,6 +1,6 @@
 = Mr.Docs
 Alan Freitas <alandefreitas@gmail.com>
-:description: Mr.Docs: A Clang/LLVM tool for building reference documentation from C++ code and javadoc comments.
+:description: Mr.Docs: A Clang/LLVM tool for building reference documentation from C++ code and documentation comments.
 :sectanchors:
 :url-repo: https://github.com/cppalliance/mrdocs
 :page-tags: mrdocs

docs/website/snippets/is_prime.cpp

@@ -4,9 +4,8 @@
 
     Linear in n.
 
-    @return Whether or not n is prime.
+    @return Whether `n` is prime.
     @param n The number to test
-
 */
 bool
 is_prime(unsigned long long n) noexcept;

include/mrdocs/ADT/ArrayView.hpp

@@ -0,0 +1,167 @@
+//
+// This is a derivative work. originally part of the LLVM Project.
+// Licensed under the Apache License v2.0 with LLVM Exceptions.
+// See https://llvm.org/LICENSE.txt for license information.
+// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+//
+// Copyright (c) 2025 Alan de Freitas (alandefreitas@gmail.com)
+//
+// Official repository: https://github.com/cppalliance/mrdocs
+//
+
+#ifndef MRDOCS_API_ADT_ARRAYVIEW_HPP
+#define MRDOCS_API_ADT_ARRAYVIEW_HPP
+
+#include <mrdocs/Platform.hpp>
+#include <algorithm>
+#include <cassert>
+#include <compare>
+#include <cstddef>
+#include <iterator>
+#include <memory>
+#include <type_traits>
+
+namespace mrdocs {
+
+/** A non-owning, read-only view over a contiguous array of T.
+
+    Similar to std::string_view but for arbitrary element type T.
+*/
+template <class T>
+class ArrayView {
+    static_assert(!std::is_void_v<T>, "ArrayView<void> is ill-formed");
+
+public:
+    // types
+    using value_type             = T;
+    using size_type              = std::size_t;
+    using difference_type        = std::ptrdiff_t;
+    using pointer                = const T*;
+    using const_pointer          = const T*;
+    using reference              = const T&;
+    using const_reference        = const T&;
+    using iterator               = const T*;
+    using const_iterator         = const T*;
+    using reverse_iterator       = std::reverse_iterator<const_iterator>;
+    using const_reverse_iterator = std::reverse_iterator<const_iterator>;
+
+    static constexpr size_type npos = static_cast<size_type>(-1);
+
+    // ctors
+    constexpr ArrayView() noexcept = default;
+
+    constexpr ArrayView(const T* data, size_type count) noexcept
+        : data_(data), size_(count) {}
+
+    template <size_type N>
+    constexpr ArrayView(const T (&arr)[N]) noexcept
+        : data_(arr), size_(N) {}
+
+    template <class It>
+    requires (std::contiguous_iterator<It> &&
+             std::same_as<std::remove_cv_t<std::remove_reference_t<std::iter_value_t<It>>>, T>)
+    constexpr ArrayView(It first, size_type count) noexcept
+        : data_(std::to_address(first)), size_(count) {}
+
+    // iterators
+    constexpr const_iterator begin()  const noexcept { return data_; }
+    constexpr const_iterator end()    const noexcept { return data_ + size_; }
+    constexpr const_iterator cbegin() const noexcept { return begin(); }
+    constexpr const_iterator cend()   const noexcept { return end(); }
+    constexpr const_reverse_iterator rbegin() const noexcept { return const_reverse_iterator(end()); }
+    constexpr const_reverse_iterator rend()   const noexcept { return const_reverse_iterator(begin()); }
+
+    // capacity
+    constexpr size_type size()   const noexcept { return size_; }
+    constexpr size_type length() const noexcept { return size_; }
+    [[nodiscard]] constexpr bool empty() const noexcept { return size_ == 0; }
+
+    // element access
+    constexpr const_reference operator[](size_type i) const noexcept {
+        return data_[i];
+    }
+    constexpr const_reference at(size_type i) const {
+        assert(i < size_);
+        return data_[i];
+    }
+    constexpr const_reference front() const {
+        assert(!empty());
+        return data_[0];
+    }
+    constexpr const_reference back() const {
+        assert(!empty());
+        return data_[size_ - 1];
+    }
+    constexpr const_pointer data() const noexcept { return data_; }
+
+    // modifiers (adjust the view; do not touch underlying data)
+    constexpr void remove_prefix(size_type n) noexcept {
+        assert(n <= size_);
+        data_ += n;
+        size_ -= n;
+    }
+    constexpr void remove_suffix(size_type n) noexcept {
+        assert(n <= size_);
+        size_ -= n;
+    }
+
+    // slicing
+    constexpr ArrayView slice(size_type pos, size_type count = npos) const noexcept {
+        assert(pos <= size_);
+        const size_type rcount = (count == npos || pos + count > size_) ? (size_ - pos) : count;
+        return ArrayView(data_ + pos, rcount);
+    }
+    constexpr ArrayView take_front(size_type n) const noexcept {
+        return slice(0, n <= size_ ? n : size_);
+    }
+    constexpr ArrayView take_back(size_type n) const noexcept {
+        n = (n <= size_) ? n : size_;
+        return slice(size_ - n, n);
+    }
+    constexpr ArrayView drop_front(size_type n) const noexcept {
+        return (n >= size_) ? ArrayView() : ArrayView(data_ + n, size_ - n);
+    }
+    constexpr ArrayView drop_back(size_type n) const noexcept {
+        return (n >= size_) ? ArrayView() : ArrayView(data_, size_ - n);
+    }
+
+    // comparisons
+    friend constexpr bool operator==(ArrayView a, ArrayView b) noexcept
+    requires requires (const T& x, const T& y) { { x == y } -> std::convertible_to<bool>; }
+    {
+        return a.size_ == b.size_ && std::equal(a.begin(), a.end(), b.begin());
+    }
+
+    friend constexpr auto operator<=>(ArrayView a, ArrayView b) noexcept
+    requires requires (const T& x, const T& y) { x <=> y; }
+    {
+        return std::lexicographical_compare_three_way(
+            a.begin(), a.end(), b.begin(), b.end(), std::compare_three_way{});
+    }
+
+private:
+    const T* data_ = nullptr;
+    size_type size_ = 0;
+};
+
+// deduction guides
+template <class T>
+ArrayView(const T*, std::size_t) -> ArrayView<T>;
+
+template <class T, std::size_t N>
+ArrayView(const T (&)[N]) -> ArrayView<T>;
+
+// helpers
+template <class T>
+constexpr ArrayView<T> make_array_view(const T* data, std::size_t count) noexcept {
+    return ArrayView<T>(data, count);
+}
+
+template <class T, std::size_t N>
+constexpr ArrayView<T> make_array_view(const T (&arr)[N]) noexcept {
+    return ArrayView<T>(arr);
+}
+
+} // mrdocs
+
+#endif // MRDOCS_API_ADT_ARRAYVIEW_HPP