From 6600fe747a86bc6c7ce4d00eb6286816b69b218e Mon Sep 17 00:00:00 2001 From: Vinnie Falco Date: Mon, 12 Jun 2023 15:13:01 -0700 Subject: [PATCH] chore: refactor Javadoc --- include/mrdox/Metadata/Javadoc.hpp | 509 +++++++++++++++-------------- source/-XML/XMLTags.cpp | 10 +- source/-XML/XMLTags.hpp | 2 +- source/-XML/XMLWriter.cpp | 72 ++-- source/-XML/XMLWriter.hpp | 20 +- source/-adoc/AdocWriter.cpp | 68 ++-- source/-adoc/AdocWriter.hpp | 22 +- source/AST/AnyBlock.hpp | 16 +- source/AST/AnyNodeList.hpp | 122 +++---- source/AST/BitcodeWriter.cpp | 44 +-- source/AST/BitcodeWriter.hpp | 2 +- source/AST/ParseJavadoc.cpp | 50 +-- source/Metadata/Javadoc.cpp | 54 +-- 13 files changed, 499 insertions(+), 492 deletions(-) diff --git a/include/mrdox/Metadata/Javadoc.hpp b/include/mrdox/Metadata/Javadoc.hpp index 36fb80667..16acb8095 100644 --- a/include/mrdox/Metadata/Javadoc.hpp +++ b/include/mrdox/Metadata/Javadoc.hpp @@ -22,285 +22,292 @@ namespace clang { namespace mrdox { -/** A processed Doxygen-style comment attached to a declaration. +// This namespace contains all of the Javadoc +// related types, constants, and functions. +namespace doc { + +using String = std::string; + +enum class Kind +{ + text = 1, // needed by bitstream + styled, + block, // used by bitcodes + paragraph, + brief, + admonition, + code, + param, + tparam, + returns +}; + +/** A text style. */ -struct MRDOX_VISIBLE - Javadoc +enum class Style { - using String = std::string; + none = 1, // needed by bitstream + mono, + bold, + italic +}; - enum class Kind : int - { - text = 1, // needed by bitstream - styled, - block, // used by bitcodes - paragraph, - brief, - admonition, - code, - param, - tparam, - returns - }; - - /** A text style. - */ - enum class Style : int +/** An admonishment style. +*/ +enum class Admonish +{ + none = 1, // needed by bitstream + note, + tip, + important, + caution, + warning +}; + +/** Parameter pass direction. +*/ +enum class ParamDirection : int +{ + none, + in, + out, + inout +}; + +//-------------------------------------------- + +/** This is a variant-like list element. +*/ +struct Node +{ + Kind kind; + + auto operator<=>( + Node const&) const noexcept = default; + + explicit Node(Kind kind_) noexcept + : kind(kind_) { - none = 1, // needed by bitstream - mono, - bold, - italic - }; + } +}; - /** An admonishment style. - */ - enum class Admonish : int +/** A string of plain text. +*/ +struct Text : Node +{ + String string; + + static constexpr Kind static_kind = Kind::text; + + auto operator<=>(Text const& + ) const noexcept = default; + + explicit + Text( + String string_ = String()) + : Node(Kind::text) + , string(std::move(string_)) { - none = 1, // needed by bitstream - note, - tip, - important, - caution, - warning - }; - - /** Parameter pass direction. - */ - enum class ParamDirection : int + } + +protected: + Text( + String string_, + Kind kind_) + : Node(kind_) + , string(std::move(string_)) { - none, - in, - out, - inout - }; + } +}; - //-------------------------------------------- +/** A piece of style text. +*/ +struct StyledText : Text +{ + Style style; - /** This is a variant-like list element. - */ - struct Node + static constexpr Kind static_kind = Kind::styled; + + auto operator<=>(StyledText const& + ) const noexcept = default; + + StyledText( + String string_ = String(), + Style style_ = Style::none) + : Text(std::move(string_), Kind::styled) + , style(style_) { - Kind kind; + } +}; - auto operator<=>(Node const& - ) const noexcept = default; +/** A piece of block content - explicit Node(Kind kind_) noexcept - : kind(kind_) - { - } - }; + The top level is a list of blocks. +*/ +struct Block : Node +{ + static constexpr Kind static_kind = Kind::block; - /** A string of plain text. - */ - struct Text : Node - { - String string; - - static constexpr Kind static_kind = Kind::text; - - auto operator<=>(Text const& - ) const noexcept = default; - - explicit - Text( - String string_ = String()) - : Node(Kind::text) - , string(std::move(string_)) - { - } - - protected: - Text( - String string_, - Kind kind_) - : Node(kind_) - , string(std::move(string_)) - { - } - }; - - /** A piece of style text. - */ - struct StyledText : Text + AnyList children; + + bool empty() const noexcept { - Style style; + return children.empty(); + } - static constexpr Kind static_kind = Kind::styled; + auto operator<=>(Block const& + ) const noexcept = default; - auto operator<=>(StyledText const& - ) const noexcept = default; +protected: + explicit + Block( + Kind kind_, + AnyList children_ = {}) noexcept + : Node(kind_) + , children(std::move(children_)) + { + } +}; - StyledText( - String string_ = String(), - Style style_ = Style::none) - : Text(std::move(string_), Kind::styled) - , style(style_) - { - } - }; +/** A sequence of text nodes. +*/ +struct Paragraph : Block +{ + static constexpr Kind static_kind = Kind::paragraph; - /** A piece of block content + auto operator<=>(Paragraph const& + ) const noexcept = default; - The top level is a list of blocks. - */ - struct Block : Node - { - static constexpr Kind static_kind = Kind::block; - - AnyList children; - - bool empty() const noexcept - { - return children.empty(); - } - - auto operator<=>(Block const& - ) const noexcept = default; - - protected: - explicit - Block( - Kind kind_, - AnyList children_ = {}) noexcept - : Node(kind_) - , children(std::move(children_)) - { - } - }; - - /** A sequence of text nodes. - */ - struct Paragraph : Block + Paragraph() noexcept + : Block(Kind::paragraph) { - static constexpr Kind static_kind = Kind::paragraph; - - auto operator<=>(Paragraph const& - ) const noexcept = default; - - Paragraph() noexcept - : Block(Kind::paragraph) - { - } - - protected: - explicit - Paragraph( - Kind kind, - AnyList children_ = {}) - : Block(kind, std::move(children_)) - { - } - }; - - /** The brief description - */ - struct Brief : Paragraph + } + +protected: + explicit + Paragraph( + Kind kind, + AnyList children_ = {}) + : Block(kind, std::move(children_)) { - static constexpr Kind static_kind = Kind::brief; + } +}; - auto operator<=>(Brief const& - ) const noexcept = default; +/** The brief description +*/ +struct Brief : Paragraph +{ + static constexpr Kind static_kind = Kind::brief; - Brief() noexcept - : Paragraph(Kind::brief) - { - } - }; + auto operator<=>(Brief const& + ) const noexcept = default; - /** Documentation for an admonition - */ - struct Admonition : Paragraph + Brief() noexcept + : Paragraph(Kind::brief) { - Admonish style; + } +}; - auto operator<=>(Admonition const& - ) const noexcept = default; +/** Documentation for an admonition +*/ +struct Admonition : Paragraph +{ + Admonish style; - explicit - Admonition( - Admonish style_ = Admonish::none) - : Paragraph(Kind::admonition) - , style(style_) - { - } - }; + auto operator<=>(Admonition const& + ) const noexcept = default; - /** Preformatted source code. - */ - struct Code : Paragraph + explicit + Admonition( + Admonish style_ = Admonish::none) + : Paragraph(Kind::admonition) + , style(style_) { - // VFALCO we can add a language (e.g. C++), - // then emit attributes in the generator. + } +}; - static constexpr Kind static_kind = Kind::code; +/** Preformatted source code. +*/ +struct Code : Paragraph +{ + // VFALCO we can add a language (e.g. C++), + // then emit attributes in the generator. - auto operator<=>(Code const& - ) const noexcept = default; + static constexpr Kind static_kind = Kind::code; - Code() - : Paragraph(Kind::code) - { - } - }; + auto operator<=>(Code const& + ) const noexcept = default; - /** Documentation for a function parameter - */ - struct Param : Paragraph + Code() + : Paragraph(Kind::code) { - String name; - ParamDirection direction; - - static constexpr Kind static_kind = Kind::param; - - auto operator<=>(Param const& - ) const noexcept = default; - - Param( - String name_ = String(), - Paragraph details_ = Paragraph(), - ParamDirection direction_ = ParamDirection::none) - : Paragraph( - Kind::param, - std::move(details_.children)) - , name(std::move(name_)) - , direction(direction_) - { - } - }; - - /** Documentation for a template parameter - */ - struct TParam : Paragraph + } +}; + +/** Documentation for a function parameter +*/ +struct Param : Paragraph +{ + String name; + ParamDirection direction; + + static constexpr Kind static_kind = Kind::param; + + auto operator<=>(Param const& + ) const noexcept = default; + + Param( + String name_ = String(), + Paragraph details_ = Paragraph(), + ParamDirection direction_ = ParamDirection::none) + : Paragraph( + Kind::param, + std::move(details_.children)) + , name(std::move(name_)) + , direction(direction_) { - String name; + } +}; - static constexpr Kind static_kind = Kind::tparam; +/** Documentation for a template parameter +*/ +struct TParam : Paragraph +{ + String name; - auto operator<=>(TParam const& - ) const noexcept = default; + static constexpr Kind static_kind = Kind::tparam; - TParam() - : Paragraph(Kind::tparam) - { - } - }; + auto operator<=>(TParam const& + ) const noexcept = default; - /** Documentation for a function return type - */ - struct Returns : Paragraph + TParam() + : Paragraph(Kind::tparam) { - static constexpr Kind static_kind = Kind::returns; + } +}; - auto operator<=>(Returns const& - ) const noexcept = default; +/** Documentation for a function return type +*/ +struct Returns : Paragraph +{ + static constexpr Kind static_kind = Kind::returns; + + auto operator<=>(Returns const& + ) const noexcept = default; + + Returns() + : Paragraph(Kind::returns) + { + } +}; - Returns() - : Paragraph(Kind::returns) - { - } - }; +} // doc + +/** A processed Doxygen-style comment attached to a declaration. +*/ +struct MRDOX_VISIBLE + Javadoc +{ //-------------------------------------------- @@ -312,7 +319,7 @@ struct MRDOX_VISIBLE MRDOX_DECL explicit Javadoc( - AnyList blocks); + AnyList blocks); /** Return true if this is empty */ @@ -325,7 +332,7 @@ struct MRDOX_VISIBLE This function should only be called after postProcess() has been invoked. */ - Paragraph const* + doc::Paragraph const* getBrief() const noexcept { return brief_.get(); @@ -333,7 +340,7 @@ struct MRDOX_VISIBLE /** Return the list of top level blocks. */ - AnyList const& + AnyList const& getBlocks() const noexcept { return blocks_; @@ -341,7 +348,7 @@ struct MRDOX_VISIBLE /** Return the element describing the return type. */ - Returns const* + doc::Returns const* getReturns() const noexcept { return returns_.get(); @@ -349,7 +356,7 @@ struct MRDOX_VISIBLE /** Return the list of top level blocks. */ - AnyList const& + AnyList const& getParams() const noexcept { return params_; @@ -357,7 +364,7 @@ struct MRDOX_VISIBLE /** Return the list of top level blocks. */ - AnyList const& + AnyList const& getTParams() const noexcept { return tparams_; @@ -365,7 +372,7 @@ struct MRDOX_VISIBLE // VFALCO This is unfortunately necessary for // the deserialization from bitcode... - AnyList& + AnyList& getBlocks() noexcept { return blocks_; @@ -442,7 +449,7 @@ struct MRDOX_VISIBLE template static void - append(Paragraph& parent, Child&& child) + append(doc::Paragraph& parent, Child&& child) { append(parent.children, std::forward(child)); @@ -451,7 +458,7 @@ struct MRDOX_VISIBLE /** Add a top level element to the doc comment. */ - void append(Block node) + void append(doc::Block node) { append(blocks_, std::move(node)); } @@ -459,11 +466,11 @@ struct MRDOX_VISIBLE //-------------------------------------------- private: - std::shared_ptr brief_; - std::shared_ptr returns_; - AnyList blocks_; - AnyList params_; - AnyList tparams_; + std::shared_ptr brief_; + std::shared_ptr returns_; + AnyList blocks_; + AnyList params_; + AnyList tparams_; }; } // mrdox diff --git a/source/-XML/XMLTags.cpp b/source/-XML/XMLTags.cpp index 1e33acc67..d5f2bf23a 100644 --- a/source/-XML/XMLTags.cpp +++ b/source/-XML/XMLTags.cpp @@ -80,16 +80,16 @@ toString( llvm::StringRef toString( - Javadoc::Style style) noexcept + doc::Style style) noexcept { switch(style) { - case Javadoc::Style::bold: return "bold"; - case Javadoc::Style::mono: return "mono"; - case Javadoc::Style::italic: return "italic"; + case doc::Style::bold: return "bold"; + case doc::Style::mono: return "mono"; + case doc::Style::italic: return "italic"; // should never get here - case Javadoc::Style::none: return ""; + case doc::Style::none: return ""; default: // unknown style diff --git a/source/-XML/XMLTags.hpp b/source/-XML/XMLTags.hpp index 7973ef7c6..e2d079a1b 100644 --- a/source/-XML/XMLTags.hpp +++ b/source/-XML/XMLTags.hpp @@ -65,7 +65,7 @@ struct xmlEscape // Converters for attributes std::string toString(SymbolID const& id); llvm::StringRef toString(InfoKind) noexcept; -llvm::StringRef toString(Javadoc::Style style) noexcept; +llvm::StringRef toString(doc::Style style) noexcept; //------------------------------------------------ diff --git a/source/-XML/XMLWriter.cpp b/source/-XML/XMLWriter.cpp index b899dc9e8..e3157deca 100644 --- a/source/-XML/XMLWriter.cpp +++ b/source/-XML/XMLWriter.cpp @@ -597,36 +597,36 @@ writeNodes( void XMLWriter:: writeNode( - Javadoc::Node const& node) + doc::Node const& node) { switch(node.kind) { - case Javadoc::Kind::text: - writeText(static_cast(node)); + case doc::Kind::text: + writeText(static_cast(node)); break; - case Javadoc::Kind::styled: - writeStyledText(static_cast(node)); + case doc::Kind::styled: + writeStyledText(static_cast(node)); break; - case Javadoc::Kind::paragraph: - writeParagraph(static_cast(node)); + case doc::Kind::paragraph: + writeParagraph(static_cast(node)); break; - case Javadoc::Kind::brief: - writeBrief(static_cast(node)); + case doc::Kind::brief: + writeBrief(static_cast(node)); break; - case Javadoc::Kind::admonition: - writeAdmonition(static_cast(node)); + case doc::Kind::admonition: + writeAdmonition(static_cast(node)); break; - case Javadoc::Kind::code: - writeCode(static_cast(node)); + case doc::Kind::code: + writeCode(static_cast(node)); break; - case Javadoc::Kind::param: - writeJParam(static_cast(node)); + case doc::Kind::param: + writeJParam(static_cast(node)); break; - case Javadoc::Kind::tparam: - writeTParam(static_cast(node)); + case doc::Kind::tparam: + writeTParam(static_cast(node)); break; - case Javadoc::Kind::returns: - writeReturns(static_cast(node)); + case doc::Kind::returns: + writeReturns(static_cast(node)); break; default: // unknown kind @@ -637,7 +637,7 @@ writeNode( void XMLWriter:: writeBrief( - Javadoc::Paragraph const& node) + doc::Paragraph const& node) { tags_.open("brief"); writeNodes(node.children); @@ -647,7 +647,7 @@ writeBrief( void XMLWriter:: writeText( - Javadoc::Text const& node) + doc::Text const& node) { tags_.indent() << "" << @@ -658,7 +658,7 @@ writeText( void XMLWriter:: writeStyledText( - Javadoc::StyledText const& node) + doc::StyledText const& node) { tags_.write(toString(node.style), node.string); } @@ -666,7 +666,7 @@ writeStyledText( void XMLWriter:: writeParagraph( - Javadoc::Paragraph const& para, + doc::Paragraph const& para, llvm::StringRef tag) { tags_.open("para", { @@ -678,24 +678,24 @@ writeParagraph( void XMLWriter:: writeAdmonition( - Javadoc::Admonition const& admonition) + doc::Admonition const& admonition) { llvm::StringRef tag; switch(admonition.style) { - case Javadoc::Admonish::note: + case doc::Admonish::note: tag = "note"; break; - case Javadoc::Admonish::tip: + case doc::Admonish::tip: tag = "tip"; break; - case Javadoc::Admonish::important: + case doc::Admonish::important: tag = "important"; break; - case Javadoc::Admonish::caution: + case doc::Admonish::caution: tag = "caution"; break; - case Javadoc::Admonish::warning: + case doc::Admonish::warning: tag = "warning"; break; default: @@ -707,7 +707,7 @@ writeAdmonition( void XMLWriter:: -writeCode(Javadoc::Code const& code) +writeCode(doc::Code const& code) { if(code.children.empty()) { @@ -723,7 +723,7 @@ writeCode(Javadoc::Code const& code) void XMLWriter:: writeReturns( - Javadoc::Returns const& returns) + doc::Returns const& returns) { if(returns.empty()) return; @@ -735,18 +735,18 @@ writeReturns( void XMLWriter:: writeJParam( - Javadoc::Param const& param) + doc::Param const& param) { const char* direction = nullptr; switch(param.direction) { - case Javadoc::ParamDirection::in: + case doc::ParamDirection::in: direction = "in"; break; - case Javadoc::ParamDirection::out: + case doc::ParamDirection::out: direction = "out"; break; - case Javadoc::ParamDirection::inout: + case doc::ParamDirection::inout: direction = "inout"; break; default: @@ -763,7 +763,7 @@ writeJParam( void XMLWriter:: writeTParam( - Javadoc::TParam const& tparam) + doc::TParam const& tparam) { tags_.open("tparam", { { "name", tparam.name, ! tparam.name.empty() }}); diff --git a/source/-XML/XMLWriter.hpp b/source/-XML/XMLWriter.hpp index 9f4191b25..93ebaee62 100644 --- a/source/-XML/XMLWriter.hpp +++ b/source/-XML/XMLWriter.hpp @@ -83,16 +83,16 @@ class XMLWriter template void writeNodes(AnyList const& list); - void writeNode(Javadoc::Node const& node); - void writeBrief(Javadoc::Paragraph const& node); - void writeText(Javadoc::Text const& node); - void writeStyledText(Javadoc::StyledText const& node); - void writeParagraph(Javadoc::Paragraph const& node, llvm::StringRef tag = ""); - void writeAdmonition(Javadoc::Admonition const& node); - void writeCode(Javadoc::Code const& node); - void writeReturns(Javadoc::Returns const& node); - void writeJParam(Javadoc::Param const& node); - void writeTParam(Javadoc::TParam const& node); + void writeNode(doc::Node const& node); + void writeBrief(doc::Paragraph const& node); + void writeText(doc::Text const& node); + void writeStyledText(doc::StyledText const& node); + void writeParagraph(doc::Paragraph const& node, llvm::StringRef tag = ""); + void writeAdmonition(doc::Admonition const& node); + void writeCode(doc::Code const& node); + void writeReturns(doc::Returns const& node); + void writeJParam(doc::Param const& node); + void writeTParam(doc::TParam const& node); }; } // xml diff --git a/source/-adoc/AdocWriter.cpp b/source/-adoc/AdocWriter.cpp index 509060495..d57fad453 100644 --- a/source/-adoc/AdocWriter.cpp +++ b/source/-adoc/AdocWriter.cpp @@ -624,39 +624,39 @@ writeFunctionDeclaration( void AdocWriter:: writeNode( - Javadoc::Node const& node) + doc::Node const& node) { switch(node.kind) { - case Javadoc::Kind::text: - writeNode(static_cast(node)); + case doc::Kind::text: + writeNode(static_cast(node)); return; - case Javadoc::Kind::styled: - writeNode(static_cast(node)); + case doc::Kind::styled: + writeNode(static_cast(node)); return; #if 0 - case Javadoc::Node::block: - writeNode(static_cast(node)); + case doc::Node::block: + writeNode(static_cast(node)); return; #endif - case Javadoc::Kind::brief: - case Javadoc::Kind::paragraph: - writeNode(static_cast(node)); + case doc::Kind::brief: + case doc::Kind::paragraph: + writeNode(static_cast(node)); return; - case Javadoc::Kind::admonition: - writeNode(static_cast(node)); + case doc::Kind::admonition: + writeNode(static_cast(node)); return; - case Javadoc::Kind::code: - writeNode(static_cast(node)); + case doc::Kind::code: + writeNode(static_cast(node)); return; - case Javadoc::Kind::param: - writeNode(static_cast(node)); + case doc::Kind::param: + writeNode(static_cast(node)); return; - case Javadoc::Kind::tparam: - writeNode(static_cast(node)); + case doc::Kind::tparam: + writeNode(static_cast(node)); return; - case Javadoc::Kind::returns: - writeNode(static_cast(node)); + case doc::Kind::returns: + writeNode(static_cast(node)); return; default: // unknown kind @@ -667,7 +667,7 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Block const&) + doc::Block const&) { // shouldn't get here MRDOX_ASSERT(false); @@ -676,9 +676,9 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Text const& node) + doc::Text const& node) { - // Text nodes must be left aligned or + // doc::Text nodes must be left aligned or // else they can be rendered up as code. os_ << llvm::StringRef(node.string).ltrim() << '\n'; } @@ -686,17 +686,17 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::StyledText const& node) + doc::StyledText const& node) { switch(node.style) { - case Javadoc::Style::bold: + case doc::Style::bold: os_ << '*' << node.string << "*\n"; break; - case Javadoc::Style::mono: + case doc::Style::mono: os_ << '`' << node.string << "`\n"; break; - case Javadoc::Style::italic: + case doc::Style::italic: os_ << '_' << node.string << "_\n"; break; default: @@ -708,7 +708,7 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Paragraph const& node) + doc::Paragraph const& node) { writeNodes(node.children); } @@ -716,7 +716,7 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Admonition const& node) + doc::Admonition const& node) { writeNodes(node.children); } @@ -724,12 +724,12 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Code const& node) + doc::Code const& node) { os_ << "[,cpp]\n" "----\n"; - AnyList const& list(node.children); + AnyList const& list(node.children); if(! list.empty()) { // measure the left margin @@ -756,21 +756,21 @@ writeNode( void AdocWriter:: writeNode( - Javadoc::Param const& node) + doc::Param const& node) { } void AdocWriter:: writeNode( - Javadoc::TParam const& node) + doc::TParam const& node) { } void AdocWriter:: writeNode( - Javadoc::Returns const& node) + doc::Returns const& node) { } diff --git a/source/-adoc/AdocWriter.hpp b/source/-adoc/AdocWriter.hpp index de31f0b27..8cf73b1f4 100644 --- a/source/-adoc/AdocWriter.hpp +++ b/source/-adoc/AdocWriter.hpp @@ -107,20 +107,20 @@ class AdocWriter { if(list.empty()) return; - for(Javadoc::Node const& node : list) + for(doc::Node const& node : list) writeNode(node); } - void writeNode(Javadoc::Node const& node); - void writeNode(Javadoc::Block const& node); - void writeNode(Javadoc::Text const& node); - void writeNode(Javadoc::StyledText const& node); - void writeNode(Javadoc::Paragraph const& node); - void writeNode(Javadoc::Admonition const& node); - void writeNode(Javadoc::Code const& node); - void writeNode(Javadoc::Param const& node); - void writeNode(Javadoc::TParam const& node); - void writeNode(Javadoc::Returns const& node); + void writeNode(doc::Node const& node); + void writeNode(doc::Block const& node); + void writeNode(doc::Text const& node); + void writeNode(doc::StyledText const& node); + void writeNode(doc::Paragraph const& node); + void writeNode(doc::Admonition const& node); + void writeNode(doc::Code const& node); + void writeNode(doc::Param const& node); + void writeNode(doc::TParam const& node); + void writeNode(doc::Returns const& node); FormalParam formalParam(Param const& ft); TypeName typeName(TypeInfo const& ti); diff --git a/source/AST/AnyBlock.hpp b/source/AST/AnyBlock.hpp index d5784cfd8..f8b3367a7 100644 --- a/source/AST/AnyBlock.hpp +++ b/source/AST/AnyBlock.hpp @@ -101,22 +101,22 @@ class JavadocNodesBlock { case JAVADOC_LIST_KIND: { - Javadoc::Kind kind{}; + doc::Kind kind{}; if(auto err = decodeRecord(R, kind, Blob)) return err; return J.setKind(kind); } case JAVADOC_NODE_KIND: { - Javadoc::Kind kind{}; + doc::Kind kind{}; if(auto err = decodeRecord(R, kind, Blob)) return err; return J.getNodes().appendChild(kind); } case JAVADOC_PARAM_DIRECTION: { - Javadoc::ParamDirection direction = - Javadoc::ParamDirection::none; + doc::ParamDirection direction = + doc::ParamDirection::none; if(auto err = decodeRecord(R, direction, Blob)) return err; return J.getNodes().setDirection(direction); @@ -127,16 +127,16 @@ class JavadocNodesBlock } case JAVADOC_NODE_STYLE: { - Javadoc::Style style = - Javadoc::Style::none; + doc::Style style = + doc::Style::none; if(auto err = decodeRecord(R, style, Blob)) return err; return J.getNodes().setStyle(style); } case JAVADOC_NODE_ADMONISH: { - Javadoc::Admonish admonish = - Javadoc::Admonish::none; + doc::Admonish admonish = + doc::Admonish::none; if(auto err = decodeRecord(R, admonish, Blob)) return err; return J.getNodes().setAdmonish(admonish); diff --git a/source/AST/AnyNodeList.hpp b/source/AST/AnyNodeList.hpp index e83ccf983..f3b6245c5 100644 --- a/source/AST/AnyNodeList.hpp +++ b/source/AST/AnyNodeList.hpp @@ -27,11 +27,11 @@ class AnyNodeList struct Nodes { virtual ~Nodes() = default; - virtual Error appendChild(Javadoc::Kind kind) = 0; - virtual Error setStyle(Javadoc::Style style) = 0; + virtual Error appendChild(doc::Kind kind) = 0; + virtual Error setStyle(doc::Style style) = 0; virtual Error setString(llvm::StringRef string) = 0; - virtual Error setAdmonish(Javadoc::Admonish admonish) = 0; - virtual Error setDirection(Javadoc::ParamDirection direction) = 0; + virtual Error setAdmonish(doc::Admonish admonish) = 0; + virtual Error setDirection(doc::ParamDirection direction) = 0; virtual AnyListNodes extractNodes() = 0; virtual void spliceBack(AnyListNodes&& nodes) noexcept = 0; }; @@ -49,7 +49,7 @@ class AnyNodeList Nodes& getNodes(); bool isTopLevel() const noexcept; - Error setKind(Javadoc::Kind kind); + Error setKind(doc::Kind kind); template Error spliceInto(AnyList& nodes); @@ -61,11 +61,11 @@ class AnyNodeList { AnyList list; - Error appendChild(Javadoc::Kind kind) override; - Error setStyle(Javadoc::Style style) override; + Error appendChild(doc::Kind kind) override; + Error setStyle(doc::Style style) override; Error setString(llvm::StringRef string) override; - Error setAdmonish(Javadoc::Admonish admonish) override; - Error setDirection(Javadoc::ParamDirection direction) override; + Error setAdmonish(doc::Admonish admonish) override; + Error setDirection(doc::ParamDirection direction) override; AnyListNodes extractNodes() override; void spliceBack(AnyListNodes&& nodes) noexcept override; }; @@ -107,12 +107,12 @@ getNodes() -> struct ErrorNodes : Nodes { - Error appendChild(Javadoc::Kind) override + Error appendChild(doc::Kind) override { return Error("kind is missing"); } - Error setStyle(Javadoc::Style) override + Error setStyle(doc::Style) override { return Error("kind is missing"); } @@ -122,12 +122,12 @@ getNodes() -> return Error("kind is missing"); } - Error setAdmonish(Javadoc::Admonish) override + Error setAdmonish(doc::Admonish) override { return Error("kind is missing"); } - Error setDirection(Javadoc::ParamDirection) override + Error setDirection(doc::ParamDirection) override { return Error("kind is missing"); } @@ -157,17 +157,17 @@ inline Error AnyNodeList:: setKind( - Javadoc::Kind kind) + doc::Kind kind) { if(nodes_ != nullptr) return Error("kind already set"); switch(kind) { - case Javadoc::Kind::block: - nodes_ = new NodesImpl(); + case doc::Kind::block: + nodes_ = new NodesImpl(); break; - case Javadoc::Kind::text: - nodes_ = new NodesImpl(); + case doc::Kind::text: + nodes_ = new NodesImpl(); break; default: return Error("wrong or unknown kind"); @@ -211,36 +211,36 @@ Error AnyNodeList:: NodesImpl:: appendChild( - Javadoc::Kind kind) + doc::Kind kind) { switch(kind) { - case Javadoc::Kind::text: - Javadoc::append(list, Javadoc::Text()); + case doc::Kind::text: + Javadoc::append(list, doc::Text()); return Error::success(); - case Javadoc::Kind::styled: - Javadoc::append(list, Javadoc::StyledText()); + case doc::Kind::styled: + Javadoc::append(list, doc::StyledText()); return Error::success(); - case Javadoc::Kind::paragraph: - Javadoc::append(list, Javadoc::Paragraph()); + case doc::Kind::paragraph: + Javadoc::append(list, doc::Paragraph()); return Error::success(); - case Javadoc::Kind::brief: - Javadoc::append(list, Javadoc::Brief()); + case doc::Kind::brief: + Javadoc::append(list, doc::Brief()); return Error::success(); - case Javadoc::Kind::admonition: - Javadoc::append(list, Javadoc::Admonition()); + case doc::Kind::admonition: + Javadoc::append(list, doc::Admonition()); return Error::success(); - case Javadoc::Kind::code: - Javadoc::append(list, Javadoc::Code()); + case doc::Kind::code: + Javadoc::append(list, doc::Code()); return Error::success(); - case Javadoc::Kind::returns: - Javadoc::append(list, Javadoc::Returns()); + case doc::Kind::returns: + Javadoc::append(list, doc::Returns()); return Error::success(); - case Javadoc::Kind::param: - Javadoc::append(list, Javadoc::Param()); + case doc::Kind::param: + Javadoc::append(list, doc::Param()); return Error::success(); - case Javadoc::Kind::tparam: - Javadoc::append(list, Javadoc::TParam()); + case doc::Kind::tparam: + Javadoc::append(list, doc::TParam()); return Error::success(); default: return Error("invalid kind"); @@ -252,13 +252,13 @@ Error AnyNodeList:: NodesImpl:: setStyle( - Javadoc::Style style) + doc::Style style) { - if constexpr(std::derived_from) + if constexpr(std::derived_from) { - if(list.back().kind != Javadoc::Kind::styled) + if(list.back().kind != doc::Kind::styled) return Error("style on wrong kind"); - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.style = style; return Error::success(); } @@ -275,25 +275,25 @@ NodesImpl:: setString( llvm::StringRef string) { - if constexpr(std::derived_from) + if constexpr(std::derived_from) { - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.string = string.str(); return Error::success(); } - else if constexpr(std::derived_from) + else if constexpr(std::derived_from) { switch(list.back().kind) { - case Javadoc::Kind::param: + case doc::Kind::param: { - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.name = string.str(); return Error::success(); } - case Javadoc::Kind::tparam: + case doc::Kind::tparam: { - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.name = string.str(); return Error::success(); } @@ -304,15 +304,15 @@ setString( #if 0 // VFALCO This was for when the top level Javadoc // has separate lists for Param and TParam - else if constexpr(std::derived_from) + else if constexpr(std::derived_from) { - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.name = string.str(); return Error::success(); } - else if constexpr(std::derived_from) + else if constexpr(std::derived_from) { - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.name = string.str(); return Error::success(); } @@ -325,13 +325,13 @@ Error AnyNodeList:: NodesImpl:: setAdmonish( - Javadoc::Admonish admonish) + doc::Admonish admonish) { - if constexpr(std::derived_from) + if constexpr(std::derived_from) { - if(list.back().kind != Javadoc::Kind::admonition) + if(list.back().kind != doc::Kind::admonition) return Error("admonish on wrong kind"); - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.style = admonish; return Error::success(); } @@ -346,13 +346,13 @@ Error AnyNodeList:: NodesImpl:: setDirection( - Javadoc::ParamDirection direction) + doc::ParamDirection direction) { - if constexpr(std::derived_from) + if constexpr(std::derived_from) { - if(list.back().kind != Javadoc::Kind::param) + if(list.back().kind != doc::Kind::param) return Error("direction on wrong kind"); - auto& node = static_cast(list.back()); + auto& node = static_cast(list.back()); node.direction = direction; return Error::success(); } @@ -378,7 +378,7 @@ NodesImpl:: spliceBack( AnyListNodes&& nodes) noexcept { - if constexpr(std::derived_from) + if constexpr(std::derived_from) { list.back().children.spliceBack(std::move(nodes)); } diff --git a/source/AST/BitcodeWriter.cpp b/source/AST/BitcodeWriter.cpp index 7c259f8c2..afed5d910 100644 --- a/source/AST/BitcodeWriter.cpp +++ b/source/AST/BitcodeWriter.cpp @@ -325,10 +325,10 @@ RecordsByBlock{ // Javadoc {BI_JAVADOC_BLOCK_ID, {}}, - // AnyList + // AnyList {BI_JAVADOC_LIST_BLOCK_ID, {JAVADOC_LIST_KIND}}, - // Javadoc::Node + // doc::Node {BI_JAVADOC_NODE_BLOCK_ID, {JAVADOC_NODE_KIND, JAVADOC_NODE_STRING, JAVADOC_NODE_STYLE, JAVADOC_NODE_ADMONISH, JAVADOC_PARAM_DIRECTION}}, @@ -724,7 +724,7 @@ emitBlock( { StreamSubBlockGuard Block(Stream, BI_JAVADOC_LIST_BLOCK_ID); emitRecord(T::static_kind, JAVADOC_LIST_KIND); - for(Javadoc::Node const& node : list) + for(doc::Node const& node : list) emitBlock(node); } @@ -851,67 +851,67 @@ emitBlock( void BitcodeWriter:: emitBlock( - Javadoc::Node const& I) + doc::Node const& I) { StreamSubBlockGuard Block(Stream, BI_JAVADOC_NODE_BLOCK_ID); emitRecord(I.kind, JAVADOC_NODE_KIND); switch(I.kind) { - case Javadoc::Kind::text: + case doc::Kind::text: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitRecord(J.string, JAVADOC_NODE_STRING); break; } - case Javadoc::Kind::styled: + case doc::Kind::styled: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitRecord(J.style, JAVADOC_NODE_STYLE); emitRecord(J.string, JAVADOC_NODE_STRING); break; } - case Javadoc::Kind::paragraph: + case doc::Kind::paragraph: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitBlock(J.children); break; } - case Javadoc::Kind::brief: + case doc::Kind::brief: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitBlock(J.children); break; } - case Javadoc::Kind::admonition: + case doc::Kind::admonition: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitRecord(J.style, JAVADOC_NODE_ADMONISH); emitBlock(J.children); break; } - case Javadoc::Kind::code: + case doc::Kind::code: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitBlock(J.children); break; } - case Javadoc::Kind::returns: + case doc::Kind::returns: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitBlock(J.children); break; } - case Javadoc::Kind::param: + case doc::Kind::param: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitRecord(J.direction, JAVADOC_PARAM_DIRECTION); emitRecord(J.name, JAVADOC_NODE_STRING); emitBlock(J.children); break; } - case Javadoc::Kind::tparam: + case doc::Kind::tparam: { - auto const& J = static_cast(I); + auto const& J = static_cast(I); emitRecord(J.name, JAVADOC_NODE_STRING); emitBlock(J.children); break; diff --git a/source/AST/BitcodeWriter.hpp b/source/AST/BitcodeWriter.hpp index b7aa550a4..a2a055aa4 100644 --- a/source/AST/BitcodeWriter.hpp +++ b/source/AST/BitcodeWriter.hpp @@ -123,7 +123,7 @@ class BitcodeWriter void emitBlock(FunctionInfo const& I); void emitBlock(Param const& I); void emitBlock(std::unique_ptr const& jd); - void emitBlock(Javadoc::Node const& I); + void emitBlock(doc::Node const& I); void emitBlock(NamespaceInfo const& I); void emitBlock(RecordInfo const& I); void emitBlock(SpecializationInfo const& T); diff --git a/source/AST/ParseJavadoc.cpp b/source/AST/ParseJavadoc.cpp index 9373ef6b8..bc3c00293 100644 --- a/source/AST/ParseJavadoc.cpp +++ b/source/AST/ParseJavadoc.cpp @@ -148,7 +148,7 @@ class JavadocVisitor #if 0 static void makeLeftAligned( - AnyList& list) + AnyList& list) { if(list.empty()) return; @@ -206,7 +206,7 @@ class JavadocVisitor // VFALCO Figure out why we get empty TextComment if(! s.empty()) Javadoc::append(*para_, - Javadoc::Text(ensureUTF8(s.str()))); + doc::Text(ensureUTF8(s.str()))); } void visitHTMLTagComment( @@ -229,17 +229,17 @@ class JavadocVisitor void visitInlineCommandComment( InlineCommandComment const* C) { - Javadoc::Style style(Javadoc::Style::none); + doc::Style style(doc::Style::none); switch (C->getRenderKind()) { case InlineCommandComment::RenderKind::RenderMonospaced: - style = Javadoc::Style::mono; + style = doc::Style::mono; break; case InlineCommandComment::RenderKind::RenderBold: - style = Javadoc::Style::bold; + style = doc::Style::bold; break; case InlineCommandComment::RenderKind::RenderEmphasized: - style = Javadoc::Style::italic; + style = doc::Style::italic; break; case InlineCommandComment::RenderKind::RenderNormal: case InlineCommandComment::RenderKind::RenderAnchor: @@ -253,7 +253,7 @@ class JavadocVisitor // emit nested styles, so only one inline // style command can be applied per args. - Javadoc::String s; + doc::String s; std::size_t n = 0; for(unsigned i = 0; i < C->getNumArgs(); ++i) n += C->getArgText(i).size(); @@ -261,12 +261,12 @@ class JavadocVisitor for(unsigned i = 0; i < C->getNumArgs(); ++i) s.append(C->getArgText(i)); - if(style != Javadoc::Style::none) + if(style != doc::Style::none) Javadoc::append(*para_, - Javadoc::StyledText(std::move(s), style)); + doc::StyledText(std::move(s), style)); else Javadoc::append(*para_, - Javadoc::Text(std::move(s))); + doc::Text(std::move(s))); } // @@ -278,7 +278,7 @@ class JavadocVisitor { if(para_) return visitChildren(C); - Javadoc::Paragraph para; + doc::Paragraph para; Scope scope(para, para_); visitChildren(C); // VFALCO Figure out why we get empty ParagraphComment @@ -301,7 +301,7 @@ class JavadocVisitor } if(cmd->IsBriefCommand) { - Javadoc::Brief brief; + doc::Brief brief; Scope scope(brief, para_); visitChildren(C->getParagraph()); Javadoc::append(blocks_, std::move(brief)); @@ -309,7 +309,7 @@ class JavadocVisitor } if(cmd->IsReturnsCommand) { - Javadoc::Returns returns; + doc::Returns returns; Scope scope(returns, para_); visitChildren(C->getParagraph()); Javadoc::append(blocks_, std::move(returns)); @@ -317,7 +317,7 @@ class JavadocVisitor } if(cmd->getID() == CommandTraits::KCI_note) { - Javadoc::Admonition para(Javadoc::Admonish::note); + doc::Admonition para(doc::Admonish::note); Scope scope(para, para_); visitChildren(C->getParagraph()); Javadoc::append(blocks_, std::move(para)); @@ -325,7 +325,7 @@ class JavadocVisitor } if(cmd->getID() == CommandTraits::KCI_warning) { - Javadoc::Admonition para(Javadoc::Admonish::warning); + doc::Admonition para(doc::Admonish::warning); Scope scope(para, para_); visitChildren(C->getParagraph()); Javadoc::append(blocks_, std::move(para)); @@ -336,7 +336,7 @@ class JavadocVisitor void visitParamCommandComment( ParamCommandComment const* C) { - Javadoc::Param param; + doc::Param param; if(C->hasParamName()) param.name = ensureUTF8(C->getParamNameAsWritten().str()); else @@ -346,13 +346,13 @@ class JavadocVisitor switch(C->getDirection()) { case ParamCommandComment::PassDirection::In: - param.direction = Javadoc::ParamDirection::in; + param.direction = doc::ParamDirection::in; break; case ParamCommandComment::PassDirection::Out: - param.direction = Javadoc::ParamDirection::out; + param.direction = doc::ParamDirection::out; break; case ParamCommandComment::PassDirection::InOut: - param.direction = Javadoc::ParamDirection::inout; + param.direction = doc::ParamDirection::inout; break; } } @@ -365,7 +365,7 @@ class JavadocVisitor void visitTParamCommandComment( TParamCommandComment const* C) { - Javadoc::TParam tparam; + doc::TParam tparam; if(C->hasParamName()) tparam.name = ensureUTF8(C->getParamNameAsWritten().str()); else @@ -379,7 +379,7 @@ class JavadocVisitor void visitVerbatimBlockComment( VerbatimBlockComment const* C) { - Javadoc::Code code; + doc::Code code; Scope scope(code, para_); //if(C->hasNonWhitespaceParagraph()) visitChildren(C); @@ -397,15 +397,15 @@ class JavadocVisitor VerbatimBlockLineComment const* C) { Javadoc::append(*para_, - Javadoc::Text(C->getText().str())); + doc::Text(C->getText().str())); } private: FullComment const* FC_; ASTContext const& ctx_; - AnyList blocks_; - AnyList params_; - Javadoc::Paragraph* para_ = nullptr; + AnyList blocks_; + AnyList params_; + doc::Paragraph* para_ = nullptr; }; //------------------------------------------------ diff --git a/source/Metadata/Javadoc.cpp b/source/Metadata/Javadoc.cpp index 797a5f6c8..8df6f4e6b 100644 --- a/source/Metadata/Javadoc.cpp +++ b/source/Metadata/Javadoc.cpp @@ -22,14 +22,14 @@ concept a_Node = std::is_copy_constructible_v && std::three_way_comparable; -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); -static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); +static_assert(a_Node); //------------------------------------------------ @@ -38,7 +38,7 @@ Javadoc() noexcept = default; Javadoc:: Javadoc( - AnyList blocks) + AnyList blocks) : blocks_(std::move(blocks)) { } @@ -77,38 +77,38 @@ void Javadoc:: postProcess() { - Paragraph* brief = nullptr; + doc::Paragraph* brief = nullptr; auto it = blocks_.begin(); while(it != blocks_.end()) { - if(it->kind == Kind::brief) + if(it->kind == doc::Kind::brief) { - brief = static_cast(&*it); + brief = static_cast(&*it); goto done; } - else if(it->kind == Kind::returns) + else if(it->kind == doc::Kind::returns) { if(! returns_) - returns_ = std::make_shared( - std::move(static_cast(*it))); + returns_ = std::make_shared( + std::move(static_cast(*it))); // unconditionally consume the Returns element it = blocks_.erase(it); // KRYSTIAN TODO: emit a warning for duplicate @returns continue; } - else if(it->kind == Kind::param) + else if(it->kind == doc::Kind::param) { it = blocks_.move_to(it, params_); continue; } - else if(it->kind == Kind::tparam) + else if(it->kind == doc::Kind::tparam) { it = blocks_.move_to(it, tparams_); continue; } - if(it->kind == Kind::paragraph && ! brief) + if(it->kind == doc::Kind::paragraph && ! brief) { - brief = static_cast(&*it); + brief = static_cast(&*it); ++it; goto find_brief; } @@ -118,17 +118,17 @@ postProcess() find_brief: while(it != blocks_.end()) { - if(it->kind == Kind::brief) + if(it->kind == doc::Kind::brief) { - brief = static_cast(&*it); + brief = static_cast(&*it); break; } - else if(it->kind == Kind::param) + else if(it->kind == doc::Kind::param) { it = blocks_.move_to(it, params_); continue; } - else if(it->kind == Kind::tparam) + else if(it->kind == doc::Kind::tparam) { it = blocks_.move_to(it, tparams_); continue; @@ -138,16 +138,16 @@ postProcess() done: if(brief != nullptr) { - brief_ = blocks_.extract_first_of( - [brief](Block& block) + brief_ = blocks_.extract_first_of( + [brief](doc::Block& block) { return brief == █ }); } else { - static std::shared_ptr empty_para = - std::make_shared(); + static std::shared_ptr empty_para = + std::make_shared(); brief_ = empty_para; } }