Skip to content

Commit 1dd7055

Browse files
vinniefalcovinniefalco
committed
refactor javadoc node hierarchy
1 parent 1455e40 commit 1dd7055

File tree

8 files changed

+146
-49
lines changed

8 files changed

+146
-49
lines changed

‎include/mrdox/meta/Javadoc.hpp

Lines changed: 97 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -272,76 +272,162 @@ struct Javadoc
272272
List<TParam> tparams,
273273
Returns returns);
274274

275+
/** Comparison
276+
277+
These are used internally to impose a
278+
total ordering, and not visible in the
279+
output format.
280+
*/
281+
/** @{ */
275282
bool operator<(Javadoc const&) const noexcept;
276283
bool operator==(Javadoc const&) const noexcept;
284+
/* @} */
277285

278286
/** Return true if this is empty
279287
*/
280288
bool
281289
empty() const noexcept;
282290

291+
/** Return the brief, or nullptr if there is none.
292+
293+
This function should only be called
294+
after calculateBrief() has been invoked.
295+
*/
283296
Paragraph const*
284297
getBrief() const noexcept
285298
{
286299
return brief_.get();
287300
}
288301

302+
/** Return the list of top level blocks.
303+
*/
289304
List<Block> const&
290305
getBlocks() const noexcept
291306
{
292307
return blocks_;
293308
}
294309

310+
/** Return a paragraph describing the return value.
311+
*/
295312
Returns const&
296313
getReturns() const noexcept
297314
{
298315
return returns_;
299316
}
300317

318+
/** Return the list of param commands
319+
*/
301320
List<Param> const&
302321
getParams() const noexcept
303322
{
304323
return params_;
305324
}
306325

326+
/** Return the list of tparam commands
327+
*/
307328
List<TParam> const&
308329
getTParams() const noexcept
309330
{
310331
return tparams_;
311332
}
312333

313-
/** Append a node to the documentation comment.,
334+
//--------------------------------------------
335+
336+
/** Merge other into this.
337+
338+
This is used to combine separate doc
339+
comments which are semantically attached
340+
to the same symbol.
314341
*/
315-
template<class Child>
342+
void merge(Javadoc& other);
343+
344+
/** Calculate the brief.
345+
346+
The implementation calls this function once,
347+
after all doc comments have been merged
348+
and attached, to calculate the brief as
349+
follows:
350+
351+
@li Sets the brief to the first paragraph
352+
in which a "brief" command exists, or
353+
354+
@li Sets the first paragraph as the brief if
355+
no "brief" is found.
356+
357+
@li Otherwise, the brief is set to a
358+
null pointer to indicate absence.
359+
*/
360+
void calculateBrief();
361+
362+
//--------------------------------------------
363+
364+
/** These are used to bottleneck all insertions.
365+
*/
366+
/** @{ */
367+
template<class T, class U>
368+
static
316369
void
317-
emplace_back(Child&& node)
370+
append(List<T>& list, List<U>&& other) noexcept
318371
{
319-
static_assert(std::is_base_of_v<Node, Child>);
372+
list.splice_back(std::move(other));
373+
}
320374

321-
blocks_.emplace_back<Child>(std::forward<Child>(node));
375+
template<class T, class Child>
376+
static
377+
void
378+
append(List<T>& list, Child&& child)
379+
{
380+
list.emplace_back(
381+
std::forward<Child>(child));
322382
}
323383

384+
template<class Parent, class Child>
385+
static
324386
void
325-
emplace_back(Param param)
387+
append(Parent& parent, Child&& child)
326388
{
327-
params_.emplace_back(std::move(param));
389+
append(parent.children,
390+
std::forward<Child>(child));
328391
}
329392

393+
template<class Child>
394+
static
330395
void
331-
emplace_back(TParam tparam)
396+
append(Paragraph& parent, Child&& child)
332397
{
333-
tparams_.emplace_back(std::move(tparam));
398+
append(parent.children,
399+
std::forward<Child>(child));
334400
}
401+
/** @} */
335402

336-
void merge(Javadoc& other);
337-
void calculateBrief();
403+
/** Add a top level element to the doc comment.
404+
*/
405+
/** @{ */
406+
void append(Block node)
407+
{
408+
append(blocks_, std::move(node));
409+
}
410+
411+
void append(Param node)
412+
{
413+
append(params_, std::move(node));
414+
}
415+
416+
void append(TParam node)
417+
{
418+
append(tparams_, std::move(node));
419+
}
420+
/** @} */
421+
422+
//--------------------------------------------
338423

339424
//private:
340425
public: // VFALCO sigh...
341426
std::shared_ptr<Paragraph const> brief_;
342427
List<Block> blocks_;
343428
List<Param> params_;
344429
List<TParam> tparams_;
430+
std::shared_ptr<Returns const> returns_ptr_;
345431
Returns returns_;
346432
};
347433

‎include/mrdox/meta/List.hpp

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -170,7 +170,7 @@ class List : public ListBase
170170
U& emplace_back(U&& u);
171171

172172
template<class U>
173-
void splice_back(List<U>& other);
173+
void splice_back(List<U>&& other) noexcept;
174174

175175
void swap(List& other);
176176

@@ -587,7 +587,7 @@ template<class U>
587587
void
588588
List<T>::
589589
splice_back(
590-
List<U>& other)
590+
List<U>&& other) noexcept
591591
{
592592
if(other.empty())
593593
return;

‎source/lib/ast/BitcodeReader.cpp

Lines changed: 15 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -967,14 +967,11 @@ readSubBlock(
967967
//llvm::outs() << "INCOMING\n";
968968
//dumpJavadoc(Javadoc(List<Javadoc::Block>(J.children), {}, {}, {}));
969969
if(J.kind == Javadoc::Kind::block)
970-
javadoc_->blocks_.splice_back(J.children);
971-
//javadoc_->blocks_ = std::move(J.children);
970+
Javadoc::append(javadoc_->blocks_, std::move(J.children));
972971
else if(J.kind == Javadoc::Kind::param)
973-
javadoc_->params_.splice_back(J.children);
974-
//javadoc_->params_ = std::move(J.children);
972+
Javadoc::append(javadoc_->params_, std::move(J.children));
975973
else if(J.kind == Javadoc::Kind::tparam)
976-
javadoc_->tparams_.splice_back(J.children);
977-
//javadoc_->tparams_ = std::move(J.children);
974+
Javadoc::append(javadoc_->tparams_, std::move(J.children));
978975
else
979976
return makeError("wrong node kind");
980977
//llvm::outs() << "AFTER\n";
@@ -992,19 +989,19 @@ readSubBlock(
992989
case Javadoc::Kind::returns:
993990
{
994991
auto& parent = static_cast<Javadoc::Paragraph&>(J.parent());
995-
parent.children.splice_back(J.children);
992+
Javadoc::append(parent.children, std::move(J.children));
996993
return llvm::Error::success();
997994
}
998995
case Javadoc::Kind::param:
999996
{
1000997
auto& parent = static_cast<Javadoc::Param&>(J.parent());
1001-
parent.children.splice_back(J.children);
998+
Javadoc::append(parent.children, std::move(J.children));
1002999
return llvm::Error::success();
10031000
}
10041001
case Javadoc::Kind::tparam:
10051002
{
10061003
auto& parent = static_cast<Javadoc::TParam&>(J.parent());
1007-
parent.children.splice_back(J.children);
1004+
Javadoc::append(parent.children, std::move(J.children));
10081005
return llvm::Error::success();
10091006
}
10101007
//case Javadoc::Kind::block
@@ -1534,31 +1531,31 @@ parseRecord(
15341531
switch(kind)
15351532
{
15361533
case Javadoc::Kind::text:
1537-
I->emplace_back(Javadoc::Text());
1534+
Javadoc::append(*I, Javadoc::Text());
15381535
return llvm::Error::success();
15391536
case Javadoc::Kind::styled:
1540-
I->emplace_back(Javadoc::StyledText());
1537+
Javadoc::append(*I, Javadoc::StyledText());
15411538
return llvm::Error::success();
15421539
case Javadoc::Kind::paragraph:
1543-
I->emplace_back(Javadoc::Paragraph());
1540+
Javadoc::append(*I, Javadoc::Paragraph());
15441541
return llvm::Error::success();
15451542
case Javadoc::Kind::brief:
1546-
I->emplace_back(Javadoc::Brief());
1543+
Javadoc::append(*I, Javadoc::Brief());
15471544
return llvm::Error::success();
15481545
case Javadoc::Kind::admonition:
1549-
I->emplace_back(Javadoc::Admonition());
1546+
Javadoc::append(*I, Javadoc::Admonition());
15501547
return llvm::Error::success();
15511548
case Javadoc::Kind::code:
1552-
I->emplace_back(Javadoc::Code());
1549+
Javadoc::append(*I, Javadoc::Code());
15531550
return llvm::Error::success();
15541551
case Javadoc::Kind::returns:
1555-
I->emplace_back(Javadoc::Returns());
1552+
Javadoc::append(*I, Javadoc::Returns());
15561553
return llvm::Error::success();
15571554
case Javadoc::Kind::param:
1558-
I->emplace_back(Javadoc::Param());
1555+
Javadoc::append(*I, Javadoc::Param());
15591556
return llvm::Error::success();
15601557
case Javadoc::Kind::tparam:
1561-
I->emplace_back(Javadoc::TParam());
1558+
Javadoc::append(*I, Javadoc::TParam());
15621559
return llvm::Error::success();
15631560
default:
15641561
llvm_unreachable("unknown kind");

‎source/lib/ast/ParseJavadoc.cpp

Lines changed: 15 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -179,8 +179,11 @@ class JavadocVisitor
179179
else
180180
s = C->getText().rtrim();
181181
//s = C->getText().ltrim().rtrim();
182-
para_->children.emplace_back(Javadoc::Text(
183-
ensureUTF8(s.str())));
182+
183+
// VFALCO Figure out why we get empty TextComment
184+
if(! s.empty())
185+
Javadoc::append(*para_,
186+
Javadoc::Text(ensureUTF8(s.str())));
184187
}
185188

186189
void visitInlineCommandComment(
@@ -218,10 +221,10 @@ class JavadocVisitor
218221
s.append(C->getArgText(i));
219222

220223
if(style != Javadoc::Style::none)
221-
para_->children.emplace_back(
224+
Javadoc::append(*para_,
222225
Javadoc::StyledText(std::move(s), style));
223226
else
224-
para_->children.emplace_back(
227+
Javadoc::append(*para_,
225228
Javadoc::Text(std::move(s)));
226229
}
227230

@@ -237,7 +240,9 @@ class JavadocVisitor
237240
Javadoc::Paragraph para;
238241
Scope scope(para, para_);
239242
visit_children(this, C);
240-
auto it = blocks_.emplace_back(std::move(para));
243+
// VFALCO Figure out why we get empty ParagraphComment
244+
if(! para.empty())
245+
Javadoc::append(blocks_, std::move(para));
241246
}
242247

243248
void
@@ -258,7 +263,7 @@ class JavadocVisitor
258263
Javadoc::Brief brief;
259264
Scope scope(brief, para_);
260265
visit_children(this, C->getParagraph());
261-
blocks_.emplace_back(std::move(brief));
266+
Javadoc::append(blocks_, std::move(brief));
262267
return;
263268
}
264269
if(cmd->IsReturnsCommand)
@@ -272,15 +277,15 @@ class JavadocVisitor
272277
Javadoc::Admonition para(Javadoc::Admonish::note);
273278
Scope scope(para, para_);
274279
visit_children(this, C->getParagraph());
275-
blocks_.emplace_back(std::move(para));
280+
Javadoc::append(blocks_, std::move(para));
276281
return;
277282
}
278283
if(cmd->getID() == CommandTraits::KCI_warning)
279284
{
280285
Javadoc::Admonition para(Javadoc::Admonish::warning);
281286
Scope scope(para, para_);
282287
visit_children(this, C->getParagraph());
283-
blocks_.emplace_back(std::move(para));
288+
Javadoc::append(blocks_, std::move(para));
284289
return;
285290
}
286291
}
@@ -324,7 +329,7 @@ class JavadocVisitor
324329
Scope scope(code, code_);
325330
//if(C->hasNonWhitespaceParagraph())
326331
visit_children(this, C);
327-
blocks_.emplace_back(std::move(code));
332+
Javadoc::append(blocks_, std::move(code));
328333
}
329334

330335
void visitVerbatimLineComment(
@@ -337,7 +342,7 @@ class JavadocVisitor
337342
void visitVerbatimBlockLineComment(
338343
VerbatimBlockLineComment const* C)
339344
{
340-
code_->children.emplace_back(
345+
Javadoc::append(*code_,
341346
Javadoc::Text(C->getText().str()));
342347
}
343348

‎source/lib/ast/Serialize.cpp

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -466,7 +466,9 @@ populateParentNamespaces(
466466
// record because that record matches the previous condition mentioned.
467467
if ((Namespaces.empty() && isa<RecordDecl>(D)) ||
468468
(!Namespaces.empty() && Namespaces.back().RefType == InfoType::IT_record))
469-
Namespaces.emplace_back(SymbolID(), "GlobalNamespace",
469+
Namespaces.emplace_back(
470+
SymbolID(),
471+
"", //"GlobalNamespace",
470472
InfoType::IT_namespace);
471473
}
472474

‎source/lib/format/XML.cpp

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -293,14 +293,19 @@ Writer::
293293
writeFunction(
294294
FunctionInfo const& I)
295295
{
296-
writeInfo(I);
296+
// location
297297
writeSymbol(I);
298+
// return type
298299
writeReturnType(I.ReturnType);
300+
// parameters
299301
for(auto const& J : I.Params)
300302
writeParam(J);
303+
// template parameters
301304
if(I.Template)
302305
for(TemplateParamInfo const& J : I.Template->Params)
303306
writeTemplateParam(J);
307+
// doc comment
308+
writeJavadoc(I.javadoc);
304309
}
305310

306311
void
@@ -482,9 +487,9 @@ writeJavadoc(Javadoc const& jd)
482487
if(auto brief = jd.getBrief())
483488
writeBrief(brief);
484489
writeReturns(jd.getReturns());
485-
writeNodes(jd.getBlocks());
486490
writeNodes(jd.getParams());
487491
writeNodes(jd.getTParams());
492+
writeNodes(jd.getBlocks());
488493
adjustNesting(-1);
489494
closeTag("doc");
490495
}

0 commit comments

Comments
 (0)