From 90632083150bb3e894d64b12bf70f5b6c589bbd5 Mon Sep 17 00:00:00 2001 From: Krystian Stasiowski Date: Fri, 11 Oct 2024 11:14:29 -0400 Subject: [PATCH] feat: support @relates --- include/mrdocs/Metadata/Javadoc.hpp | 25 +++++++++++++ .../generator/adoc/partials/symbol.adoc.hbs | 10 ++++++ src/lib/AST/ParseJavadoc.cpp | 35 +++++++++++++++++-- src/lib/Gen/hbs/HandlebarsCorpus.cpp | 9 +++++ src/lib/Metadata/Javadoc.cpp | 15 ++++++++ 5 files changed, 92 insertions(+), 2 deletions(-) diff --git a/include/mrdocs/Metadata/Javadoc.hpp b/include/mrdocs/Metadata/Javadoc.hpp index 43da81c9e..6eb4aabde 100644 --- a/include/mrdocs/Metadata/Javadoc.hpp +++ b/include/mrdocs/Metadata/Javadoc.hpp @@ -126,6 +126,7 @@ enum class Kind throws, details, see, + related, precondition, postcondition }; @@ -358,6 +359,25 @@ struct Copied : Reference } }; +/** A reference to a related symbol. +*/ +struct Related : Reference +{ + static constexpr Kind static_kind = Kind::related; + + Related(String string_ = String()) noexcept + : Reference(std::move(string_), Kind::related) + { + } + + bool operator==(Related const&) const noexcept = default; + bool equals(Node const& other) const noexcept override + { + return kind == other.kind && + *this == static_cast(other); + } +}; + //------------------------------------------------ // // Block nodes @@ -802,6 +822,8 @@ visit( return f.template operator()(std::forward(args)...); case Kind::postcondition: return f.template operator()(std::forward(args)...); + case Kind::related: + return f.template operator()(std::forward(args)...); default: return f.template operator()(std::forward(args)...); } @@ -867,6 +889,8 @@ visit( return visitor.template visit(); case Kind::postcondition: return visitor.template visit(); + case Kind::related: + return visitor.template visit(); default: MRDOCS_UNREACHABLE(); } @@ -901,6 +925,7 @@ struct Overview std::vector sees; std::vector preconditions; std::vector postconditions; + std::vector related; }; MRDOCS_DECL dom::String toString(Style style) noexcept; diff --git a/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs b/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs index 420edff49..ea2a228c0 100644 --- a/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs +++ b/share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs @@ -219,3 +219,13 @@ {{/each}} {{/if}} +{{! Related }} +{{#if symbol.doc.related}} +{{#> markup/dynamic-level-h }}Related{{/markup/dynamic-level-h}} + +{{#each symbol.doc.related}} +{{{.}}} + +{{/each}} + +{{/if}} diff --git a/src/lib/AST/ParseJavadoc.cpp b/src/lib/AST/ParseJavadoc.cpp index 12e57993c..36fef4d0d 100644 --- a/src/lib/AST/ParseJavadoc.cpp +++ b/src/lib/AST/ParseJavadoc.cpp @@ -1034,6 +1034,38 @@ visitInlineCommandComment( } return; } + // KRYSTIAN FIXME: these need to be made inline commands in clang + case CommandTraits::KCI_related: + case CommandTraits::KCI_relates: + { + if(! goodArgCount(1, *C)) + return; + // The parsed reference often includes characters + // that are not valid in identifiers, so we need to + // clean it up. + // Find the first character that is not a valid C++ + // identifier character, and truncate the string there. + // This potentially creates two text nodes. + auto const s = C->getArgText(0).str(); + std::string_view ref = parseQualifiedIdentifier(s); + bool const hasExtraText = ref.size() != s.size(); + if (!ref.empty()) + { + // the referenced symbol will be resolved during + // the finalization step once all symbols are extracted + emplaceText( + C->hasTrailingNewline() && !hasExtraText, + std::string(ref)); + } + // Emplace the rest of the string as doc::Text + if(hasExtraText) + { + emplaceText( + C->hasTrailingNewline(), + s.substr(ref.size())); + } + return; + } default: break; @@ -1546,8 +1578,7 @@ JavadocVisitor:: visitVerbatimLineComment( VerbatimLineComment const* C) { - // VFALCO This doesn't seem to be used - // in any of my codebases, follow up + emplaceText(true, C->getText().str()); } void diff --git a/src/lib/Gen/hbs/HandlebarsCorpus.cpp b/src/lib/Gen/hbs/HandlebarsCorpus.cpp index df0a46d57..cdbcfb55a 100644 --- a/src/lib/Gen/hbs/HandlebarsCorpus.cpp +++ b/src/lib/Gen/hbs/HandlebarsCorpus.cpp @@ -99,6 +99,14 @@ domCreate( return corpus.toStringFn(corpus, I); } +dom::Value +domCreate( + const doc::Related& I, + const HandlebarsCorpus& corpus) +{ + return corpus.toStringFn(corpus, I); +} + dom::Value domCreate( const doc::Precondition& I, @@ -256,6 +264,7 @@ getJavadoc(Javadoc const& jd) const emplaceObjectArray("see", ov.sees); emplaceObjectArray("preconditions", ov.preconditions); emplaceObjectArray("postconditions", ov.postconditions); + emplaceObjectArray("related", ov.related); return dom::Object(std::move(objKeyValues)); } diff --git a/src/lib/Metadata/Javadoc.cpp b/src/lib/Metadata/Javadoc.cpp index 9e0e11638..3391fd948 100644 --- a/src/lib/Metadata/Javadoc.cpp +++ b/src/lib/Metadata/Javadoc.cpp @@ -259,6 +259,8 @@ makeOverview( { case doc::Kind::brief: break; + case doc::Kind::related: + break; case doc::Kind::returns: ov.returns = static_cast< doc::Returns const*>(it->get()); @@ -292,6 +294,19 @@ makeOverview( break; ov.blocks.push_back(it->get()); } + + for(const auto& child : it->get()->children) + { + switch(child->kind) + { + case doc::Kind::related: + ov.related.push_back(static_cast< + doc::Related const*>(child.get())); + break; + default: + break; + } + } } return ov;