Skip to content

Commit

Permalink
feat: support @throw/@throws/@exception
Browse files Browse the repository at this point in the history
sdkrystian committed Dec 15, 2023
1 parent 2c87ded commit 0f25c6a
Showing 9 changed files with 122 additions and 65 deletions.
54 changes: 51 additions & 3 deletions include/mrdocs/Metadata/Javadoc.hpp
Original file line number Diff line number Diff line change
@@ -58,7 +58,8 @@ enum class Kind
styled,
tparam,
reference,
copied
copied,
throws
};

/** A text style.
@@ -122,8 +123,12 @@ struct MRDOCS_DECL
{
}

bool isBlock() const noexcept;
bool isText() const noexcept;
virtual bool isBlock() const noexcept = 0;

bool isText() const noexcept
{
return ! isBlock();
}

bool operator==(const Node&)const noexcept = default;
virtual bool equals(const Node& other) const noexcept
@@ -158,6 +163,11 @@ struct Text : Node
{
}

bool isBlock() const noexcept final override
{
return false;
}

bool operator==(const Text&) const noexcept = default;
bool equals(const Node& other) const noexcept override
{
@@ -295,6 +305,11 @@ struct MRDOCS_DECL
{
List<Text> children;

bool isBlock() const noexcept final override
{
return true;
}

bool empty() const noexcept
{
return children.empty();
@@ -549,6 +564,34 @@ struct TParam : Paragraph
}
};

/** Documentation for a function parameter
*/
struct Throws : Paragraph
{
String exception;

static constexpr Kind static_kind = Kind::throws;

Throws(
String exception_ = String(),
Paragraph details_ = Paragraph())
: Paragraph(
Kind::throws,
std::move(details_.children))
, exception(std::move(exception_))
{
}

bool operator==(const Throws&)
const noexcept = default;

bool equals(const Node& other) const noexcept override
{
return kind == other.kind &&
*this == static_cast<const Throws&>(other);
}
};

//------------------------------------------------

template<class F, class... Args>
@@ -588,6 +631,8 @@ visit(
return f.template operator()<Text>(std::forward<Args>(args)...);
case Kind::tparam:
return f.template operator()<TParam>(std::forward<Args>(args)...);
case Kind::throws:
return f.template operator()<Throws>(std::forward<Args>(args)...);
default:
return f.template operator()<void>(std::forward<Args>(args)...);
}
@@ -637,6 +682,8 @@ visit(
return visitor.template visit<Text>();
case Kind::tparam:
return visitor.template visit<TParam>();
case Kind::throws:
return visitor.template visit<Throws>();
default:
MRDOCS_UNREACHABLE();
}
@@ -661,6 +708,7 @@ struct Overview
Returns const* returns = nullptr;
std::vector<Param const*> params;
std::vector<TParam const*> tparams;
std::vector<Throws const*> exceptions;
};

MRDOCS_DECL dom::String toString(Style style) noexcept;
3 changes: 2 additions & 1 deletion mrdocs.rnc
Original file line number Diff line number Diff line change
@@ -330,7 +330,7 @@ grammar

BlockNode = (
Admonition | Brief | Code | Heading | ListItem |
Paragraph | Param | Returns | TParam )
Paragraph | Param | Returns | TParam | Throws )

Admonition = Paragraph
Brief = element brief { TextNode * }
@@ -345,6 +345,7 @@ grammar
attribute class { text } ?,
TextNode * }
Returns = element returns { TextNode * }
Throws = element throws { TextNode * }
TParam = element tparam {
attribute name { text } ?,
TextNode * }
7 changes: 7 additions & 0 deletions src/lib/AST/AnyBlock.hpp
Original file line number Diff line number Diff line change
@@ -396,6 +396,9 @@ class JavadocNodesBlock
case doc::Kind::tparam:
nodes.emplace_back(std::make_unique<doc::TParam>());
break;
case doc::Kind::throws:
nodes.emplace_back(std::make_unique<doc::Throws>());
break;
default:
return formatError("unknown doc::Kind");
}
@@ -426,6 +429,10 @@ class JavadocNodesBlock
static_cast<doc::TParam*>(
node)->name = Blob.str();
return Error::success();
case doc::Kind::throws:
static_cast<doc::Throws*>(
node)->exception = Blob.str();
return Error::success();
default:
return formatError("string on wrong kind");
}
2 changes: 2 additions & 0 deletions src/lib/AST/BitcodeWriter.cpp
Original file line number Diff line number Diff line change
@@ -945,6 +945,8 @@ emitBlock(
emitRecord(J.id, JAVADOC_NODE_SYMBOLREF);
if constexpr(requires { J.name; })
emitRecord(J.name, JAVADOC_NODE_STRING);
if constexpr(requires { J.exception; })
emitRecord(J.exception, JAVADOC_NODE_STRING);
if constexpr(requires { J.children; })
emitBlock(J.children);
});
34 changes: 31 additions & 3 deletions src/lib/AST/ParseJavadoc.cpp
Original file line number Diff line number Diff line change
@@ -521,7 +521,38 @@ visitBlockCommandComment(
jd_.emplace_back(std::move(returns));
return;
}
case CommandTraits::KCI_throw:
case CommandTraits::KCI_throws:
case CommandTraits::KCI_exception:
{
doc::Throws throws;
auto scope = enterScope(throws);
visitChildren(C->getParagraph());
// KRYSTIAN NOTE: clang doesn't consider these commands
// to have any arguments, so we have to extract the exception
// type manually
if(! throws.children.empty())
{
// string will start with a non-whitespace character
doc::String& text =
throws.children.front()->string;
constexpr char ws[] = " \t\n\v\f\r";
const auto except_end = text.find_first_of(ws);
throws.exception = text.substr(0, except_end);
// find the start of the next word, ignoring whitespace
const auto word_start =
text.find_first_not_of(ws, except_end);
// if we ran out of string, remove this block
if(word_start == doc::String::npos)
throws.children.erase(throws.children.begin());
// otherwise, trim the string to exclude the argument
else
text.erase(0, word_start);
}

jd_.emplace_back(std::move(throws));
return;
}
case CommandTraits::KCI_addindex:
case CommandTraits::KCI_addtogroup:
case CommandTraits::KCI_anchor:
@@ -576,7 +607,6 @@ visitBlockCommandComment(
case CommandTraits::KCI_endxmlonly:
case CommandTraits::KCI_enum:
case CommandTraits::KCI_example:
case CommandTraits::KCI_exception:
case CommandTraits::KCI_extends:
case CommandTraits::KCI_flparen: // @f(
case CommandTraits::KCI_frparen: // @f)
@@ -682,8 +712,6 @@ visitBlockCommandComment(
case CommandTraits::KCI_subsubsection:
case CommandTraits::KCI_tableofcontents:
case CommandTraits::KCI_test:
case CommandTraits::KCI_throw:
case CommandTraits::KCI_throws:
case CommandTraits::KCI_todo:
case CommandTraits::KCI_tparam:
case CommandTraits::KCI_typedef:
9 changes: 9 additions & 0 deletions src/lib/Gen/adoc/AdocCorpus.cpp
Original file line number Diff line number Diff line change
@@ -52,6 +52,7 @@ class DocVisitor
void operator()(doc::Styled const& I);
void operator()(doc::TParam const& I);
void operator()(doc::Reference const& I);
void operator()(doc::Throws const& I);

std::size_t measureLeftMargin(
doc::List<doc::Text> const& list);
@@ -201,6 +202,13 @@ operator()(doc::Returns const& I)
//dest_ += I.string;
}

void
DocVisitor::
operator()(doc::Throws const& I)
{
//dest_ += I.string;
}

void
DocVisitor::
operator()(doc::Text const& I)
@@ -338,6 +346,7 @@ class DomJavadoc : public dom::LazyObjectImpl
maybeEmplace(list, "returns", *ov.returns);
maybeEmplace(list, "params", ov.params);
maybeEmplace(list, "tparams", ov.tparams);
maybeEmplace(list, "exceptions", ov.exceptions);

return dom::Object(std::move(list));
}
15 changes: 15 additions & 0 deletions src/lib/Gen/xml/XMLWriter.cpp
Original file line number Diff line number Diff line change
@@ -663,6 +663,9 @@ writeNode(
case doc::Kind::copied:
writeCopied(static_cast<doc::Copied const&>(node));
break;
case doc::Kind::throws:
writeThrows(static_cast<doc::Throws const&>(node));
break;
default:
// unknown kind
MRDOCS_UNREACHABLE();
@@ -830,6 +833,18 @@ writeReturns(
tags_.close("returns");
}

void
XMLWriter::
writeThrows(
doc::Throws const& throws)
{
if(throws.empty())
return;
tags_.open("throws");
writeNodes(throws.children);
tags_.close("throws");
}

void
XMLWriter::
writeJParam(
1 change: 1 addition & 0 deletions src/lib/Gen/xml/XMLWriter.hpp
Original file line number Diff line number Diff line change
@@ -96,6 +96,7 @@ class XMLWriter
void writeTParam(doc::TParam const& node);
void writeReference(doc::Reference const& node);
void writeCopied(doc::Copied const& node);
void writeThrows(doc::Throws const& node);
};

} // xml
62 changes: 4 additions & 58 deletions src/lib/Metadata/Javadoc.cpp
Original file line number Diff line number Diff line change
@@ -22,64 +22,6 @@ namespace mrdocs {

namespace doc {

bool
Node::
isBlock() const noexcept
{
switch(kind)
{
case Kind::text:
case Kind::link:
case Kind::styled:
case Kind::reference:
case Kind::copied:
return false;

case Kind::admonition:
case Kind::brief:
case Kind::code:
case Kind::heading:
case Kind::list_item:
case Kind::paragraph:
case Kind::param:
case Kind::returns:
case Kind::tparam:
return true;

default:
MRDOCS_UNREACHABLE();
}
}

bool
Node::
isText() const noexcept
{
switch(kind)
{
case Kind::text:
case Kind::link:
case Kind::styled:
case Kind::reference:
case Kind::copied:
return true;

case Kind::admonition:
case Kind::brief:
case Kind::code:
case Kind::heading:
case Kind::list_item:
case Kind::paragraph:
case Kind::param:
case Kind::returns:
case Kind::tparam:
return false;

default:
MRDOCS_UNREACHABLE();
}
}

Text&
Block::
emplace_back(
@@ -328,6 +270,10 @@ makeOverview(
ov.tparams.push_back(static_cast<
doc::TParam const*>(it->get()));
break;
case doc::Kind::throws:
ov.exceptions.push_back(static_cast<
doc::Throws const*>(it->get()));
break;
default:
if(ov.brief == it->get())
break;

0 comments on commit 0f25c6a

Please sign in to comment.