Skip to content

Commit d448757

Browse files
sdkrystiansdkrystian
authored
feat: support @relates (#698)
closes #243
1 parent f5cf9d8 commit d448757

File tree

15 files changed

+384
-60
lines changed

15 files changed

+384
-60
lines changed

‎include/mrdocs/Metadata/Javadoc.hpp

+27-56
Original file line numberDiff line numberDiff line change
@@ -120,6 +120,7 @@ enum class NodeKind
120120
throws,
121121
details,
122122
see,
123+
related,
123124
precondition,
124125
postcondition
125126
};
@@ -374,6 +375,26 @@ struct Copied final : Reference
374375
}
375376
};
376377

378+
/** A reference to a related symbol.
379+
*/
380+
struct Related final : Reference
381+
{
382+
static constexpr auto static_kind = NodeKind::related;
383+
384+
Related(std::string string_ = std::string()) noexcept
385+
: Reference(std::move(string_), NodeKind::related)
386+
{
387+
}
388+
389+
auto operator<=>(Related const&) const = default;
390+
bool operator==(Related const&) const noexcept = default;
391+
bool equals(Node const& other) const noexcept override
392+
{
393+
return Kind == other.Kind &&
394+
*this == dynamic_cast<Related const&>(other);
395+
}
396+
};
397+
377398
//------------------------------------------------
378399
//
379400
// Block nodes
@@ -877,62 +898,6 @@ struct Postcondition : Paragraph
877898

878899
//------------------------------------------------
879900

880-
/** A visitor for node types.
881-
*/
882-
template<class F, class... Args>
883-
constexpr
884-
auto
885-
visit(
886-
NodeKind kind,
887-
F&& f, Args&&... args)
888-
{
889-
switch(kind)
890-
{
891-
case NodeKind::admonition:
892-
return f.template operator()<Admonition>(std::forward<Args>(args)...);
893-
case NodeKind::brief:
894-
return f.template operator()<Brief>(std::forward<Args>(args)...);
895-
case NodeKind::code:
896-
return f.template operator()<Code>(std::forward<Args>(args)...);
897-
case NodeKind::heading:
898-
return f.template operator()<Heading>(std::forward<Args>(args)...);
899-
case NodeKind::link:
900-
return f.template operator()<Link>(std::forward<Args>(args)...);
901-
case NodeKind::reference:
902-
return f.template operator()<Reference>(std::forward<Args>(args)...);
903-
case NodeKind::copied:
904-
return f.template operator()<Copied>(std::forward<Args>(args)...);
905-
case NodeKind::list_item:
906-
return f.template operator()<ListItem>(std::forward<Args>(args)...);
907-
case NodeKind::unordered_list:
908-
return f.template operator()<UnorderedList>(std::forward<Args>(args)...);
909-
case NodeKind::paragraph:
910-
return f.template operator()<Paragraph>(std::forward<Args>(args)...);
911-
case NodeKind::param:
912-
return f.template operator()<Param>(std::forward<Args>(args)...);
913-
case NodeKind::returns:
914-
return f.template operator()<Returns>(std::forward<Args>(args)...);
915-
case NodeKind::styled:
916-
return f.template operator()<Styled>(std::forward<Args>(args)...);
917-
case NodeKind::text:
918-
return f.template operator()<Text>(std::forward<Args>(args)...);
919-
case NodeKind::tparam:
920-
return f.template operator()<TParam>(std::forward<Args>(args)...);
921-
case NodeKind::throws:
922-
return f.template operator()<Throws>(std::forward<Args>(args)...);
923-
case NodeKind::details:
924-
return f.template operator()<Details>(std::forward<Args>(args)...);
925-
case NodeKind::see:
926-
return f.template operator()<See>(std::forward<Args>(args)...);
927-
case NodeKind::precondition:
928-
return f.template operator()<Precondition>(std::forward<Args>(args)...);
929-
case NodeKind::postcondition:
930-
return f.template operator()<Postcondition>(std::forward<Args>(args)...);
931-
default:
932-
return f.template operator()<void>(std::forward<Args>(args)...);
933-
}
934-
}
935-
936901
/** Visit a node.
937902
938903
@param node The node to visit.
@@ -995,6 +960,8 @@ visit(
995960
return visitor.template visit<Precondition>();
996961
case NodeKind::postcondition:
997962
return visitor.template visit<Postcondition>();
963+
case NodeKind::related:
964+
return visitor.template visit<Related>();
998965
default:
999966
MRDOCS_UNREACHABLE();
1000967
}
@@ -1063,6 +1030,9 @@ struct MRDOCS_DECL
10631030
/// The list of "see also" references.
10641031
std::vector<doc::See> sees;
10651032

1033+
/// The list of "related" references.
1034+
std::vector<SymbolID> related;
1035+
10661036
/// The list of preconditions.
10671037
std::vector<doc::Precondition> preconditions;
10681038

@@ -1093,6 +1063,7 @@ struct MRDOCS_DECL
10931063
tparams.empty() &&
10941064
exceptions.empty() &&
10951065
sees.empty() &&
1066+
related.empty() &&
10961067
preconditions.empty() &&
10971068
postconditions.empty();
10981069
}

‎mrdocs.rnc

+2-1
Original file line numberDiff line numberDiff line change
@@ -416,7 +416,7 @@ grammar
416416
Postcondition = element post { TextNode * }
417417
Details = element details { TextNode * }
418418

419-
TextNode = ( Link | Styled | Text | Reference | Copied )
419+
TextNode = ( Link | Styled | Text | Reference | Related | Copied )
420420

421421
Link = element link { attribute href { text }, text }
422422
Styled = (
@@ -426,6 +426,7 @@ grammar
426426
element italic { text } )
427427
Text = element text { text }
428428
Reference = element reference { ID ?, text }
429+
Related = element relates { ID ?, text }
429430
Copied =
430431
element (
431432
copydoc |

‎share/mrdocs/addons/generator/adoc/partials/symbol.adoc.hbs

+5
Original file line numberDiff line numberDiff line change
@@ -68,6 +68,11 @@
6868
{{#if symbol.usingDirectives}}
6969
{{>symbol/members-table members=symbol.usingDirectives title="Using Directives"}}
7070

71+
{{/if}}
72+
{{! Related symbols }}
73+
{{#if symbol.doc.related}}
74+
{{>symbol/members-table members=symbol.doc.related title="Related functions"}}
75+
7176
{{/if}}
7277
{{! Description }}
7378
{{#if symbol.doc.description}}

‎src/lib/AST/ParseJavadoc.cpp

+32
Original file line numberDiff line numberDiff line change
@@ -1122,6 +1122,38 @@ visitInlineCommandComment(
11221122
}
11231123
return;
11241124
}
1125+
// KRYSTIAN FIXME: these need to be made inline commands in clang
1126+
case CommandTraits::KCI_related:
1127+
case CommandTraits::KCI_relates:
1128+
{
1129+
if(! goodArgCount(1, *C))
1130+
return;
1131+
// The parsed reference often includes characters
1132+
// that are not valid in identifiers, so we need to
1133+
// clean it up.
1134+
// Find the first character that is not a valid C++
1135+
// identifier character, and truncate the string there.
1136+
// This potentially creates two text nodes.
1137+
auto const s = C->getArgText(0).str();
1138+
std::string_view ref = parseQualifiedIdentifier(s);
1139+
bool const hasExtraText = ref.size() != s.size();
1140+
if (!ref.empty())
1141+
{
1142+
// the referenced symbol will be resolved during
1143+
// the finalization step once all symbols are extracted
1144+
emplaceText<doc::Related>(
1145+
C->hasTrailingNewline() && !hasExtraText,
1146+
std::string(ref));
1147+
}
1148+
// Emplace the rest of the string as doc::Text
1149+
if(hasExtraText)
1150+
{
1151+
emplaceText<doc::Text>(
1152+
C->hasTrailingNewline(),
1153+
s.substr(ref.size()));
1154+
}
1155+
return;
1156+
}
11251157

11261158
default:
11271159
break;

‎src/lib/Gen/adoc/DocVisitor.cpp

+3
Original file line numberDiff line numberDiff line change
@@ -287,6 +287,9 @@ void
287287
DocVisitor::
288288
operator()(doc::Reference const& I) const
289289
{
290+
if (I.Kind == doc::NodeKind::related)
291+
return;
292+
290293
if (I.id == SymbolID::invalid)
291294
{
292295
return (*this)(static_cast<doc::Text const&>(I));

‎src/lib/Gen/hbs/HandlebarsCorpus.cpp

+10-1
Original file line numberDiff line numberDiff line change
@@ -98,6 +98,14 @@ domCreate(
9898
return corpus.toStringFn(corpus, I);
9999
}
100100

101+
dom::Value
102+
domCreate(
103+
SymbolID const& I,
104+
HandlebarsCorpus const& corpus)
105+
{
106+
return corpus.get(I);
107+
}
108+
101109
dom::Value
102110
domCreate(
103111
doc::Precondition const& I,
@@ -225,7 +233,7 @@ getJavadoc(Javadoc const& jd) const
225233
elements.reserve(nodes.size());
226234
for (value_type const& elem : nodes)
227235
{
228-
if constexpr (requires { !elem; })
236+
if constexpr (requires { *elem; })
229237
{
230238
if (!elem)
231239
{
@@ -257,6 +265,7 @@ getJavadoc(Javadoc const& jd) const
257265
emplaceObjectArray("tparams", jd.tparams);
258266
emplaceObjectArray("exceptions", jd.exceptions);
259267
emplaceObjectArray("see", jd.sees);
268+
emplaceObjectArray("related", jd.related);
260269
emplaceObjectArray("preconditions", jd.preconditions);
261270
emplaceObjectArray("postconditions", jd.postconditions);
262271
return dom::Object(std::move(objKeyValues));

‎src/lib/Gen/html/DocVisitor.cpp

+3
Original file line numberDiff line numberDiff line change
@@ -285,6 +285,9 @@ void
285285
DocVisitor::
286286
operator()(doc::Reference const& I) const
287287
{
288+
if (I.Kind == doc::NodeKind::related)
289+
return;
290+
288291
if (I.id == SymbolID::invalid)
289292
{
290293
return (*this)(static_cast<doc::Text const&>(I));

‎src/lib/Gen/xml/XMLWriter.cpp

+13
Original file line numberDiff line numberDiff line change
@@ -785,6 +785,9 @@ writeNode(doc::Node const& node)
785785
case doc::NodeKind::copied:
786786
writeCopied(dynamic_cast<doc::Copied const&>(node));
787787
break;
788+
case doc::NodeKind::related:
789+
writeRelated(dynamic_cast<doc::Related const&>(node));
790+
break;
788791
case doc::NodeKind::throws:
789792
writeThrows(dynamic_cast<doc::Throws const&>(node));
790793
break;
@@ -841,6 +844,16 @@ writeCopied(
841844
});
842845
}
843846

847+
void
848+
XMLWriter::
849+
writeRelated(
850+
doc::Related const& node)
851+
{
852+
tags_.write("relates", node.string, {
853+
{ node.id }
854+
});
855+
}
856+
844857
void
845858
XMLWriter::
846859
writeLink(

‎src/lib/Gen/xml/XMLWriter.hpp

+1
Original file line numberDiff line numberDiff line change
@@ -89,6 +89,7 @@ class XMLWriter
8989
void writeTParam(doc::TParam const& node);
9090
void writeReference(doc::Reference const& node);
9191
void writeCopied(doc::Copied const& node);
92+
void writeRelated(doc::Related const& node);
9293
void writeThrows(doc::Throws const& node);
9394
void writeDetails(doc::Details const& node, llvm::StringRef tag = "");
9495
void writeSee(doc::See const& node, llvm::StringRef tag = "");

‎src/lib/Metadata/Finalizers/JavadocFinalizer.cpp

+13-2
Original file line numberDiff line numberDiff line change
@@ -114,8 +114,18 @@ finalize(doc::Reference& ref, bool const emitWarning)
114114
{
115115
if (auto resRef = corpus_.lookup(current_context_->id, ref.string))
116116
{
117-
Info const& res = *resRef;
117+
// KRYSTIAN NOTE: we should provide an overload that
118+
// returns a non-const reference.
119+
auto& res = const_cast<Info&>(resRef->get());
118120
ref.id = res.id;
121+
if(ref.Kind == doc::NodeKind::related)
122+
{
123+
if(! res.javadoc)
124+
res.javadoc.emplace();
125+
auto& related = res.javadoc->related;
126+
if(std::ranges::find(related, current_context_->id) == related.end())
127+
related.emplace_back(current_context_->id);
128+
}
119129
}
120130
else if (
121131
emitWarning &&
@@ -150,7 +160,8 @@ finalize(doc::Node& node)
150160
finalize(N.children);
151161
}
152162

153-
if constexpr(std::same_as<NodeTy, doc::Reference>)
163+
if constexpr(std::same_as<NodeTy, doc::Reference> ||
164+
std::same_as<NodeTy, doc::Related>)
154165
{
155166
finalize(dynamic_cast<doc::Reference&>(N), true);
156167
}

‎src/lib/Metadata/Javadoc.cpp

+1
Original file line numberDiff line numberDiff line change
@@ -211,6 +211,7 @@ operator==(Javadoc const& other) const noexcept
211211
tparams == other.tparams &&
212212
exceptions == other.exceptions &&
213213
sees == other.sees &&
214+
related == other.related &&
214215
preconditions == other.preconditions &&
215216
postconditions == other.postconditions;
216217
}

0 commit comments

Comments
 (0)