feat: safe names

include/mrdox/Metadata/DomMetadata.hpp

@@ -35,10 +35,6 @@ class MRDOX_DECL
     std::unique_ptr<Impl> impl_;
 
 public:
-    /** The Corpus associated with the Dom.
-    */
-    Corpus const& corpus;
-
     /** Destructor.
     */
     virtual ~DomCorpus();
@@ -51,26 +47,30 @@ class MRDOX_DECL
 
         @param corpus The Corpus whose metadata to use.
     */
-    explicit
     DomCorpus(Corpus const& corpus);
 
-    /** Return a Dom object representing the given symbol.
+    /** Returns the Corpus associated with the Dom.
+    */
+    Corpus const& getCorpus() const;
 
-        @return A value containing the symbol contents.
+    /** Construct a Dom object representing the given symbol.
 
-        @param id The id of the symbol to return.
+        This function is called internally when a `dom::Object`
+        representing a symbol needs to be constructed because
+        it was not found in the cache.
     */
+    virtual
     dom::Object
-    get(SymbolID const& id) const;
+    construct(Info const& I) const;
 
     /** Return a Dom object representing the given symbol.
 
         @return A value containing the symbol contents.
 
-        @param I The metadata for the symbol.
+        @param id The id of the symbol to return.
     */
     dom::Object
-    get(Info const& I) const;
+    get(SymbolID const& id) const;
 
     /** Return a Dom object representing the given symbol.
 

include/mrdox/Metadata/Function.hpp

@@ -28,11 +28,15 @@ namespace clang {
 namespace mrdox {
 
 /** Return the name of an operator as a string.
+
+    @param include_keyword Whether the name
+    should be prefixed with the `operator` keyword.
 */
 MRDOX_DECL
 std::string_view
 getOperatorName(
-    OperatorKind kind) noexcept;
+    OperatorKind kind,
+    bool include_keyword = false) noexcept;
 
 /** Return the short name of an operator as a string.
 */
@@ -42,11 +46,15 @@ getShortOperatorName(
     OperatorKind kind) noexcept;
 
 /** Return the safe name of an operator as a string.
+
+    @param include_keyword Whether the name
+    should be prefixed with `operator_`.
 */
 MRDOX_DECL
 std::string_view
 getSafeOperatorName(
-    OperatorKind kind) noexcept;
+    OperatorKind kind,
+    bool include_keyword = false) noexcept;
 
 /** Function classifications */
 enum class FunctionClass

share/mrdox/addons/generator/asciidoc/layouts/single-symbol.adoc.hbs

@@ -1,3 +1,4 @@
+{{#if relfileprefix}}:relfileprefix: {{relfileprefix}}{{/if}}
 {{#with symbol}}
 {{> (lookup . 'kind') symbol=.}}
 {{/with}}

share/mrdox/addons/generator/asciidoc/partials/declarator-before.adoc.hbs

@@ -18,5 +18,5 @@
 {{#if cv-qualifiers~}}
     {{#if pointee-type}} {{cv-qualifiers}}{{else}}{{cv-qualifiers}} {{/if~}}
 {{/if~}}
-{{#if id}}{{>xref .}}[{{name}}]{{else if name}}{{name}}{{/if~}}
+{{#if symbol}}{{>xref symbol}}[{{name}}]{{else if name}}{{name}}{{/if~}}
 {{#if (eq kind "specialization")}}{{>template-args args=args}}{{/if}}

share/mrdox/addons/generator/asciidoc/partials/enum.adoc.hbs

@@ -1,6 +1,6 @@
 {{!-- enum --}}
 [#{{symbol.id}}]
-== {{symbol.name}}
+== {{#if symbol.name}}Enum {{symbol.name}}{{else}}Unnamed enum{{/if}}
 
 {{symbol.doc.brief}}
 

share/mrdox/addons/generator/asciidoc/partials/namespace.adoc.hbs

@@ -1,6 +1,6 @@
 {{!-- namespace --}}
 [#{{symbol.id}}]
-== Namespace {{symbol.name}}
+== {{#if symbol.name}}Namespace {{symbol.name}}{{else}}Unnamed namespace{{/if}}
 
 [,cols=2]
 |===

share/mrdox/addons/generator/asciidoc/partials/record.adoc.hbs

@@ -1,6 +1,6 @@
 {{!-- record --}}
 [#{{symbol.id}}]
-== {{symbol.name}}
+== {{#if symbol.name}}Class {{symbol.name}}{{else}}Unnamed class{{/if}}
 
 {{symbol.doc.brief}}
 

share/mrdox/addons/generator/asciidoc/partials/template-arg.adoc.hbs

@@ -3,6 +3,6 @@
 {{else if (eq kind "non-type")~}}
 {{~value~}}
 {{else if (eq kind "template")~}}
-{{#if template}}{{>xref id=template}}[{{name~}}]{{else~}}{{name~}}{{/if~}}
+{{#if template}}{{>xref template}}[{{name~}}]{{else~}}{{name~}}{{/if~}}
 {{/if~}}
 {{~#if is-pack}}...{{/if~}}

share/mrdox/addons/generator/asciidoc/partials/xref.adoc.hbs

@@ -1 +1 @@
-xref:{{id}}{{#if (is_multipage)}}#{{/if}}
+xref:{{ref}}{{#if (is_multipage)}}#{{/if}}

share/mrdox/addons/generator/html/partials/declarator-before.html.hbs

@@ -4,11 +4,11 @@
 {{~else if (eq kind "tag")~}}
     {{#if cv-qualifiers}}{{cv-qualifiers}} {{/if~}}
     {{#if parent-type~}}{{>declarator parent-type decl-name="" decl-name-targs=""}}::{{/if~}}
-    {{#if id}}{{>xref id=id content=name}}{{else}}{{name~}}{{/if}}
+    {{#if symbol}}{{>xref symbol content=name}}{{else}}{{name~}}{{/if}}
 {{~else if (eq kind "specialization")~}}
     {{#if cv-qualifiers}}{{cv-qualifiers}} {{/if~}}
     {{#if parent-type~}}{{>declarator parent-type decl-name="" decl-name-targs=""}}::{{/if~}}
-    {{#if id}}{{>xref id=id content=name}}{{else}}{{name~}}{{/if}}
+    {{#if symbol}}{{>xref symbol content=name}}{{else}}{{name~}}{{/if}}
     {{~>template-args args=args~}}
 {{~else if (eq kind "lvalue-reference")~}}
     {{~>declarator-before pointee-type~}}

src/lib/-HTML/Builder.cpp

@@ -30,7 +30,7 @@ Builder(
     DomCorpus const& domCorpus,
     Options const& options)
     : domCorpus_(domCorpus)
-    , corpus_(domCorpus_.corpus)
+    , corpus_(domCorpus_.getCorpus())
     , options_(options)
 {
     namespace fs = llvm::sys::fs;

src/lib/-HTML/HTMLGenerator.cpp

@@ -29,11 +29,11 @@ Expected<ExecutorGroup<Builder>>
 createExecutors(
     DomCorpus const& domCorpus)
 {
-    auto options = loadOptions(domCorpus.corpus);
+    auto options = loadOptions(domCorpus.getCorpus());
     if(! options)
         return options.error();
 
-    auto const& config = domCorpus.corpus.config;
+    auto const& config = domCorpus.getCorpus().config;
     auto& threadPool = config.threadPool();
     ExecutorGroup<Builder> group(threadPool);
     for(auto i = threadPool.getThreadCount(); i--;)

src/lib/-XML/XMLWriter.cpp

@@ -173,11 +173,11 @@ writeIndex()
         SafeNames names(corpus_);
         for(auto I : corpus_.index())
         {
-            auto safe_name = names.get(I->id);
+            auto safe_name = names.getUnqualified(I->id);
             tags_.write("symbol", {}, {
                 { "safe", safe_name },
                 { "name", corpus_.getFullyQualifiedName(*I, temp) },
-                { "tag", getTagName(*I) },
+                { "tag", toString(I->Kind) },
                 { I->id } });
         }
     }
@@ -186,7 +186,7 @@ writeIndex()
         for(auto I : corpus_.index())
             tags_.write("symbol", {}, {
                 { "name", corpus_.getFullyQualifiedName(*I, temp) },
-                { "tag", getTagName(*I) },
+                { "tag", toString(I->Kind) },
                 { I->id } });
     }
     tags_.close("symbols");

src/lib/-adoc/AdocCorpus.cpp

@@ -10,6 +10,7 @@
 //
 
 #include "AdocCorpus.hpp"
+#include "lib/Support/Radix.hpp"
 #include <mrdox/Support/RangeFor.hpp>
 #include <mrdox/Support/String.hpp>
 #include <fmt/format.h>
@@ -329,6 +330,50 @@ class DomJavadoc : public dom::LazyObjectImpl
 
 } // (anon)
 
+dom::Object
+AdocCorpus::
+construct(Info const& I) const
+{
+    // wraps a DomInfo with a lazy object which
+    // adds additional properties to the wrapped
+    // object once constructed.
+    struct AdocInfo :
+        public dom::LazyObjectImpl
+    {
+        Info const& I_;
+        AdocCorpus const& adocCorpus_;
+
+    public:
+        AdocInfo(
+            Info const& I,
+            AdocCorpus const& adocCorpus) noexcept
+            : I_(I)
+            , adocCorpus_(adocCorpus)
+        {
+        }
+
+        dom::Object construct() const override
+        {
+            auto obj = adocCorpus_.DomCorpus::construct(I_);
+            obj.set("ref", adocCorpus_.getXref(I_.id));
+            return obj;
+        }
+    };
+    return dom::newObject<AdocInfo>(I, *this);
+}
+
+std::string
+AdocCorpus::
+getXref(SymbolID const& id) const
+{
+    if(! safe_names)
+        // no safenames, use the SymbolID for references
+        return toBase16(id);
+    // use '/' as the seperator for multi-page, and '-' for single-page
+    return safe_names->getQualified(id,
+        getCorpus().config->multiPage ? '/' : '-');
+}
+
 dom::Value
 AdocCorpus::
 getJavadoc(

src/lib/-adoc/AdocCorpus.hpp

@@ -12,7 +12,10 @@
 #define MRDOX_LIB_ADOC_ADOCCORPUS_HPP
 
 #include <mrdox/Platform.hpp>
+#include "lib/Support/SafeNames.hpp"
+#include "Options.hpp"
 #include <mrdox/Metadata/DomMetadata.hpp>
+#include <optional>
 
 namespace clang {
 namespace mrdox {
@@ -21,13 +24,25 @@ namespace adoc {
 class AdocCorpus : public DomCorpus
 {
 public:
-    explicit
+    Options options;
+    std::optional<SafeNames> safe_names;
+
     AdocCorpus(
-        Corpus const& corpus)
+        Corpus const& corpus,
+        Options&& opts)
         : DomCorpus(corpus)
+        , options(std::move(opts))
     {
+        if(options.safe_names)
+            safe_names.emplace(corpus);
     }
 
+    dom::Object
+    construct(Info const& I) const override;
+
+    std::string
+    getXref(SymbolID const& id) const;
+
     dom::Value
     getJavadoc(
         Javadoc const& jd) const override;

src/lib/-adoc/AdocGenerator.cpp

@@ -27,20 +27,16 @@ namespace adoc {
 
 Expected<ExecutorGroup<Builder>>
 createExecutors(
-    DomCorpus const& domCorpus)
+    AdocCorpus const& adocCorpus)
 {
-    auto options = loadOptions(domCorpus.corpus);
-    if(! options)
-        return options.error();
-
-    auto const& config = domCorpus.corpus.config;
+    auto const& config = adocCorpus.getCorpus().config;
     auto& threadPool = config.threadPool();
     ExecutorGroup<Builder> group(threadPool);
     for(auto i = threadPool.getThreadCount(); i--;)
     {
         try
         {
-           group.emplace(domCorpus, *options);
+           group.emplace(adocCorpus);
         }
         catch(Exception const& ex)
         {
@@ -65,7 +61,11 @@ build(
     if(! corpus.config->multiPage)
         return Generator::build(outputPath, corpus);
 
-    AdocCorpus domCorpus(corpus);
+    auto options = loadOptions(corpus);
+    if(! options)
+        return options.error();
+
+    AdocCorpus domCorpus(corpus, options.release());
     auto ex = createExecutors(domCorpus);
     if(! ex)
         return ex.error();
@@ -84,7 +84,11 @@ buildOne(
     std::ostream& os,
     Corpus const& corpus) const
 {
-    AdocCorpus domCorpus(corpus);
+    auto options = loadOptions(corpus);
+    if(! options)
+        return options.error();
+
+    AdocCorpus domCorpus(corpus, options.release());
     auto ex = createExecutors(domCorpus);
     if(! ex)
         return ex.error();