Skip to content

Commit f069410

Browse files
alandefreitasalandefreitas
committed
preprocess related symbols
#feat
1 parent 37b782e commit f069410

File tree

15 files changed

+222
-96
lines changed

15 files changed

+222
-96
lines changed

‎include/mrdocs/Metadata/Javadoc.hpp‎

Lines changed: 17 additions & 52 deletions
Original file line numberDiff line numberDiff line change
@@ -123,7 +123,6 @@ enum class NodeKind
123123
throws,
124124
details,
125125
see,
126-
related,
127126
precondition,
128127
postcondition
129128
};
@@ -651,52 +650,6 @@ tag_invoke(
651650
v = dom::LazyObject(I, domCorpus);
652651
}
653652

654-
/** A reference to a related symbol.
655-
*/
656-
struct Related final : Reference
657-
{
658-
static constexpr auto static_kind = NodeKind::related;
659-
660-
Related(std::string string_ = std::string()) noexcept
661-
: Reference(std::move(string_), NodeKind::related)
662-
{
663-
}
664-
665-
auto operator<=>(Related const&) const = default;
666-
bool operator==(Related const&) const noexcept = default;
667-
bool equals(Node const& other) const noexcept override
668-
{
669-
return Kind == other.Kind &&
670-
*this == dynamic_cast<Related const&>(other);
671-
}
672-
};
673-
674-
/** Map the @ref Related to a @ref dom::Object.
675-
*/
676-
template <class IO>
677-
void
678-
tag_invoke(
679-
dom::LazyObjectMapTag t,
680-
IO& io,
681-
Related const& I,
682-
DomCorpus const* domCorpus)
683-
{
684-
tag_invoke(t, io, dynamic_cast<Reference const&>(I), domCorpus);
685-
}
686-
687-
/** Return the @ref Related as a @ref dom::Value object.
688-
*/
689-
inline
690-
void
691-
tag_invoke(
692-
dom::ValueFromTag,
693-
dom::Value& v,
694-
Related const& I,
695-
DomCorpus const* domCorpus)
696-
{
697-
v = dom::LazyObject(I, domCorpus);
698-
}
699-
700653
//------------------------------------------------
701654
//
702655
// Block nodes
@@ -1632,8 +1585,6 @@ visit(
16321585
return visitor.template visit<Precondition>();
16331586
case NodeKind::postcondition:
16341587
return visitor.template visit<Postcondition>();
1635-
case NodeKind::related:
1636-
return visitor.template visit<Related>();
16371588
default:
16381589
MRDOCS_UNREACHABLE();
16391590
}
@@ -1698,15 +1649,26 @@ struct MRDOCS_DECL
16981649
/// The list of "see also" references.
16991650
std::vector<doc::See> sees;
17001651

1701-
/// The list of "related" references.
1702-
std::vector<SymbolID> related;
1703-
17041652
/// The list of preconditions.
17051653
std::vector<doc::Precondition> preconditions;
17061654

17071655
/// The list of postconditions.
17081656
std::vector<doc::Postcondition> postconditions;
17091657

1658+
/** The list of "relates" references.
1659+
1660+
These references are creates with the
1661+
\\relates command.
1662+
*/
1663+
std::vector<doc::Reference> relates;
1664+
1665+
/** The list of "related" references.
1666+
1667+
These references are the inverse of
1668+
the \\relates command.
1669+
*/
1670+
std::vector<doc::Reference> related;
1671+
17101672
/** Constructor.
17111673
*/
17121674
MRDOCS_DECL
@@ -1865,6 +1827,9 @@ tag_invoke(
18651827
io.defer("sees", [&I, domCorpus] {
18661828
return dom::LazyArray(I.sees, domCorpus);
18671829
});
1830+
io.defer("relates", [&I, domCorpus] {
1831+
return dom::LazyArray(I.relates, domCorpus);
1832+
});
18681833
io.defer("related", [&I, domCorpus] {
18691834
return dom::LazyArray(I.related, domCorpus);
18701835
});

‎mrdocs.rnc‎

Lines changed: 7 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -390,7 +390,8 @@ grammar
390390
BlockNode = (
391391
Admonition | Brief | Code | Heading | ListItem |
392392
UnorderedList | Paragraph | Param | Returns | TParam |
393-
Throws | See | Precondition | Postcondition | Details)
393+
Throws | See | Precondition | Postcondition | Details |
394+
Related | Relates)
394395

395396
Admonition = Paragraph
396397
Brief = element brief { TextNode * }
@@ -417,7 +418,10 @@ grammar
417418
Postcondition = element post { TextNode * }
418419
Details = element details { TextNode * }
419420

420-
TextNode = ( Link | Styled | Text | Reference | Related | Copied )
421+
Related = element related { Reference * }
422+
Relates = element relates { Reference * }
423+
424+
TextNode = ( Link | Styled | Text | Reference | Copied )
421425

422426
Link = element link { attribute href { text }, text }
423427
Styled = (
@@ -427,7 +431,7 @@ grammar
427431
element italic { text } )
428432
Text = element text { text }
429433
Reference = element reference { ID ?, text }
430-
Related = element relates { ID ?, text }
434+
431435
Copied =
432436
element (
433437
copydoc |

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

Lines changed: 26 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -46,7 +46,8 @@
4646

4747
[,cols=2]
4848
|===
49-
|Name |Description
49+
| Name
50+
| Description
5051
{{#each (filter_by symbol.constants "isRegular" "isSeeBelow")}}
5152
{{#if (ne kind "enum-constant")}}
5253
|xref:{{{anchor}}}[`{{>symbol/name . nolink=true}}`]
@@ -66,7 +67,30 @@
6667
{{/if}}
6768
{{! Related symbols }}
6869
{{#if symbol.doc.related}}
69-
{{>symbol/members-table members=symbol.doc.related title="Related functions"}}
70+
{{#> markup/dynamic-level-h }}Non-Member Functions{{/markup/dynamic-level-h}}
71+
[,cols=2]
72+
|===
73+
| Name
74+
| Description
75+
{{#each symbol.doc.related}}
76+
| {{> javadoc/reference }}
77+
| {{> javadoc/inline-brief symbol.doc.brief }}
78+
{{/each}}
79+
|===
80+
81+
{{/if}}
82+
{{! Relates symbols }}
83+
{{#if symbol.doc.relates }}
84+
{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
85+
[,cols=2]
86+
|===
87+
| Name
88+
| Description
89+
{{#each symbol.doc.relates }}
90+
| {{> javadoc/reference }}
91+
| {{> javadoc/inline-brief symbol.doc.brief }}
92+
{{/each}}
93+
|===
7094

7195
{{/if}}
7296
{{! Description }}

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

Lines changed: 39 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@
7272
{{else}}
7373
<td>{{>symbol/name . nolink=true}}</td>
7474
{{/if}}
75-
<td>{{> javadoc/brief doc.brief }}</td>
75+
<td>{{> javadoc/inline-brief doc.brief }}</td>
7676
</tr>
7777
{{/each}}
7878
</tbody>
@@ -86,6 +86,44 @@
8686

8787
</div>
8888

89+
{{/if}}
90+
{{! Related symbols }}
91+
{{#if symbol.doc.related}}
92+
<div>
93+
{{#> markup/dynamic-level-h }}Non-Member Functions{{/markup/dynamic-level-h}}
94+
<table>
95+
<thead>
96+
<tr>
97+
<th>Name</th>
98+
<th>Description</th>
99+
</tr>
100+
</thead>
101+
<tbody>
102+
{{#each symbol.doc.related}}
103+
<tr><td>{{> javadoc/reference }}</td><td>{{> javadoc/inline-brief symbol.doc.brief }}</td></tr>
104+
{{/each}}
105+
</tbody>
106+
</table>
107+
</div>
108+
{{/if}}
109+
{{! Relates symbols }}
110+
{{#if symbol.doc.relates }}
111+
<div>
112+
{{#> markup/dynamic-level-h }}Non-Member Of{{/markup/dynamic-level-h}}
113+
<table>
114+
<thead>
115+
<tr>
116+
<th>Name</th>
117+
<th>Description</th>
118+
</tr>
119+
</thead>
120+
<tbody>
121+
{{#each symbol.doc.relates }}
122+
<tr><td>{{> javadoc/reference }}</td><td>{{> javadoc/inline-brief symbol.doc.brief }}</td></tr>
123+
{{/each}}
124+
</tbody>
125+
</table>
126+
</div>
89127
{{/if}}
90128
{{! Description }}
91129
{{#if symbol.doc.description}}

‎src/lib/AST/ParseJavadoc.cpp‎

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1024,14 +1024,19 @@ visitInlineCommandComment(
10241024
// KRYSTIAN FIXME: these need to be made inline commands in clang
10251025
case CommandTraits::KCI_related:
10261026
case CommandTraits::KCI_relates:
1027+
// MrDocs doesn't document members inline, so there's no
1028+
// distinction between "related" and "relatedalso"
1029+
case CommandTraits::KCI_relatedalso:
1030+
case CommandTraits::KCI_relatesalso:
1031+
// Member of is a concept used only in C. MrDocs handles
1032+
// it as a non-member function is all cases.
1033+
case CommandTraits::KCI_memberof:
10271034
{
10281035
MRDOCS_CHECK_OR(goodArgCount(1, *C));
10291036
std::string ref = C->getArgText(0).str();
10301037
std::string leftOver = fixReference(ref);
10311038
bool const hasExtra = !leftOver.empty();
1032-
emplaceText<doc::Related>(
1033-
C->hasTrailingNewline() && !hasExtra,
1034-
ref);
1039+
jd_.relates.emplace_back(std::move(ref));
10351040
if (hasExtra)
10361041
{
10371042
emplaceText<doc::Text>(

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

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -48,6 +48,8 @@ constexpr auto templateTagName = "template";
4848
constexpr auto tparamTagName = "tparam";
4949
constexpr auto unionTagName = "union";
5050
constexpr auto varTagName = "variable";
51+
constexpr auto relatedTagName = "related";
52+
constexpr auto relatesTagName = "relates";
5153

5254
inline dom::String getNameForValue(...)
5355
{

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

Lines changed: 12 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -733,6 +733,18 @@ writeJavadoc(
733733
writeNodes(javadoc->sees);
734734
writeNodes(javadoc->preconditions);
735735
writeNodes(javadoc->postconditions);
736+
if (!javadoc->relates.empty())
737+
{
738+
tags_.open(relatesTagName);
739+
writeNodes(javadoc->relates);
740+
tags_.close(relatesTagName);
741+
}
742+
if (!javadoc->related.empty())
743+
{
744+
tags_.open(relatedTagName);
745+
writeNodes(javadoc->related);
746+
tags_.close(relatedTagName);
747+
}
736748
tags_.close(javadocTagName);
737749
}
738750

@@ -788,9 +800,6 @@ writeNode(doc::Node const& node)
788800
case doc::NodeKind::copied:
789801
writeCopied(dynamic_cast<doc::Copied const&>(node));
790802
break;
791-
case doc::NodeKind::related:
792-
writeRelated(dynamic_cast<doc::Related const&>(node));
793-
break;
794803
case doc::NodeKind::throws:
795804
writeThrows(dynamic_cast<doc::Throws const&>(node));
796805
break;
@@ -844,16 +853,6 @@ writeCopied(
844853
});
845854
}
846855

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

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

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,6 @@ 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);
9392
void writeThrows(doc::Throws const& node);
9493
void writeSee(doc::See const& node, llvm::StringRef tag = "");
9594
void writePrecondition(doc::Precondition const& node);

0 commit comments

Comments
 (0)