feat: support @pre and @post

sdkrystian · May 30, 2024 · 5fee793 · 5fee793
1 parent 9576c73
commit 5fee793
Show file tree

Hide file tree

Showing 10 changed files with 187 additions and 3 deletions.
diff --git a/include/mrdocs/Metadata/Javadoc.hpp b/include/mrdocs/Metadata/Javadoc.hpp
@@ -129,7 +129,9 @@ enum class Kind
     copied,
     throws,
     details,
-    see
+    see,
+    precondition,
+    postcondition
 };
 
 /** A text style.
@@ -709,6 +711,50 @@ struct Throws : Paragraph
     }
 };
 
+struct Precondition : Paragraph
+{
+    static constexpr Kind static_kind = Kind::precondition;
+
+    Precondition(
+        Paragraph details_ = Paragraph())
+        : Paragraph(
+            Kind::precondition,
+            std::move(details_.children))
+    {
+    }
+
+    bool operator==(const Precondition&)
+        const noexcept = default;
+
+    bool equals(const Node& other) const noexcept override
+    {
+        return kind == other.kind &&
+            *this == static_cast<const Precondition&>(other);
+    }
+};
+
+struct Postcondition : Paragraph
+{
+    static constexpr Kind static_kind = Kind::postcondition;
+
+    Postcondition(
+        Paragraph details_ = Paragraph())
+        : Paragraph(
+            Kind::postcondition,
+            std::move(details_.children))
+    {
+    }
+
+    bool operator==(const Postcondition&)
+        const noexcept = default;
+
+    bool equals(const Node& other) const noexcept override
+    {
+        return kind == other.kind &&
+            *this == static_cast<const Postcondition&>(other);
+    }
+};
+
 //------------------------------------------------
 
 /** A visitor for node types.
@@ -756,6 +802,10 @@ visit(
         return f.template operator()<Details>(std::forward<Args>(args)...);
     case Kind::see:
         return f.template operator()<See>(std::forward<Args>(args)...);
+    case Kind::precondition:
+        return f.template operator()<Precondition>(std::forward<Args>(args)...);
+    case Kind::postcondition:
+        return f.template operator()<Postcondition>(std::forward<Args>(args)...);
     default:
         return f.template operator()<void>(std::forward<Args>(args)...);
     }
@@ -817,6 +867,10 @@ visit(
         return visitor.template visit<Details>();
     case Kind::see:
         return visitor.template visit<See>();
+    case Kind::precondition:
+        return visitor.template visit<Precondition>();
+    case Kind::postcondition:
+        return visitor.template visit<Postcondition>();
     default:
         MRDOCS_UNREACHABLE();
     }
@@ -849,6 +903,8 @@ struct Overview
     std::vector<TParam const*> tparams;
     std::vector<Throws const*> exceptions;
     std::vector<See const*> sees;
+    std::vector<Precondition const*> preconditions;
+    std::vector<Postcondition const*> postconditions;
 };
 
 MRDOCS_DECL dom::String toString(Style style) noexcept;

diff --git a/share/mrdocs/addons/generator/asciidoc/partials/symbols/function.adoc.hbs b/share/mrdocs/addons/generator/asciidoc/partials/symbols/function.adoc.hbs
@@ -54,6 +54,24 @@
 
 {{/if}}
 
+{{#if symbol.doc.preconditions}}
+== Preconditions
+
+{{#each symbol.doc.preconditions}}
+{{.}}
+{{/each}}
+
+{{/if}}
+
+{{#if symbol.doc.postconditions}}
+== Postconditions
+
+{{#each symbol.doc.postconditions}}
+{{.}}
+{{/each}}
+
+{{/if}}
+
 {{#if symbol.doc.see}}
 == See Also
 

diff --git a/src/lib/AST/AnyBlock.hpp b/src/lib/AST/AnyBlock.hpp
@@ -418,6 +418,12 @@ class JavadocNodesBlock
             case doc::Kind::see:
                 nodes.emplace_back(std::make_unique<doc::See>());
                 break;
+            case doc::Kind::precondition:
+                nodes.emplace_back(std::make_unique<doc::Precondition>());
+                break;
+            case doc::Kind::postcondition:
+                nodes.emplace_back(std::make_unique<doc::Postcondition>());
+                break;
             default:
                 return formatError("unknown doc::Kind");
             }

diff --git a/src/lib/AST/ParseJavadoc.cpp b/src/lib/AST/ParseJavadoc.cpp
@@ -1051,6 +1051,23 @@ visitBlockCommandComment(
         jd_.emplace_back(std::move(paragraph));
         return;
     }
+    case CommandTraits::KCI_pre:
+    {
+        doc::Precondition paragraph;
+        auto scope = enterScope(paragraph);
+        visitChildren(C->getParagraph());
+        jd_.emplace_back(std::move(paragraph));
+        return;
+    }
+    case CommandTraits::KCI_post:
+    {
+        doc::Postcondition paragraph;
+        auto scope = enterScope(paragraph);
+        visitChildren(C->getParagraph());
+        jd_.emplace_back(std::move(paragraph));
+        return;
+    }
+
     case CommandTraits::KCI_addindex:
     case CommandTraits::KCI_addtogroup:
     case CommandTraits::KCI_anchor:
@@ -1158,8 +1175,6 @@ visitBlockCommandComment(
     case CommandTraits::KCI_paragraph:
     case CommandTraits::KCI_param:
     case CommandTraits::KCI_parblock:
-    case CommandTraits::KCI_post:
-    case CommandTraits::KCI_pre:
     case CommandTraits::KCI_private:
     case CommandTraits::KCI_privatesection:
     case CommandTraits::KCI_property:

diff --git a/src/lib/Gen/adoc/AdocCorpus.cpp b/src/lib/Gen/adoc/AdocCorpus.cpp
@@ -390,6 +390,30 @@ domCreate(
     return s;
 }
 
+static
+dom::Value
+domCreate(
+    const doc::Precondition& I,
+    const AdocCorpus& corpus)
+{
+    std::string s;
+    DocVisitor visitor(corpus, s);
+    visitor(static_cast<const doc::Precondition&>(I));
+    return s;
+}
+
+static
+dom::Value
+domCreate(
+    const doc::Postcondition& I,
+    const AdocCorpus& corpus)
+{
+    std::string s;
+    DocVisitor visitor(corpus, s);
+    visitor(static_cast<const doc::Postcondition&>(I));
+    return s;
+}
+
 //------------------------------------------------
 
 class DomJavadoc : public dom::LazyObjectImpl
@@ -477,6 +501,8 @@ class DomJavadoc : public dom::LazyObjectImpl
         maybeEmplaceArray(list, "tparams", ov.tparams);
         maybeEmplaceArray(list, "exceptions", ov.exceptions);
         maybeEmplaceArray(list, "see", ov.sees);
+        maybeEmplaceArray(list, "preconditions", ov.preconditions);
+        maybeEmplaceArray(list, "postconditions", ov.postconditions);
 
         return dom::Object(std::move(list));
     }

diff --git a/src/lib/Gen/xml/XMLWriter.cpp b/src/lib/Gen/xml/XMLWriter.cpp
@@ -745,6 +745,12 @@ writeNode(
     case doc::Kind::see:
         writeSee(dynamic_cast<doc::See const&>(node));
         break;
+    case doc::Kind::precondition:
+        writePrecondition(dynamic_cast<doc::Precondition const&>(node));
+        break;
+    case doc::Kind::postcondition:
+        writePostcondition(dynamic_cast<doc::Postcondition const&>(node));
+        break;
     default:
         // unknown kind
         MRDOCS_UNREACHABLE();
@@ -879,6 +885,26 @@ writeSee(
     tags_.close("see");
 }
 
+void
+XMLWriter::
+writePrecondition(
+    doc::Precondition const& para)
+{
+    tags_.open("pre", {});
+    writeNodes(para.children);
+    tags_.close("pre");
+}
+
+void
+XMLWriter::
+writePostcondition(
+    doc::Postcondition const& para)
+{
+    tags_.open("post", {});
+    writeNodes(para.children);
+    tags_.close("post");
+}
+
 void
 XMLWriter::
 writeAdmonition(

diff --git a/src/lib/Gen/xml/XMLWriter.hpp b/src/lib/Gen/xml/XMLWriter.hpp
@@ -101,6 +101,8 @@ class XMLWriter
     void writeThrows(doc::Throws const& node);
     void writeDetails(doc::Details const& node, llvm::StringRef tag = "");
     void writeSee(doc::See const& node, llvm::StringRef tag = "");
+    void writePrecondition(doc::Precondition const& node);
+    void writePostcondition(doc::Postcondition const& node);
 };
 
 } // xml

diff --git a/src/lib/Metadata/Javadoc.cpp b/src/lib/Metadata/Javadoc.cpp
@@ -278,6 +278,14 @@ makeOverview(
             ov.sees.push_back(static_cast<
                 doc::See const*>(it->get()));
             break;
+        case doc::Kind::precondition:
+            ov.preconditions.push_back(static_cast<
+                doc::Precondition const*>(it->get()));
+            break;
+        case doc::Kind::postcondition:
+            ov.postconditions.push_back(static_cast<
+                doc::Postcondition const*>(it->get()));
+            break;
         default:
             if(ov.brief == it->get())
                 break;

diff --git a/test-files/old-tests/pre-post.cpp b/test-files/old-tests/pre-post.cpp
@@ -0,0 +1,7 @@
+/**
+    @pre first precondition
+    @pre second precondition
+
+    @post first postcondition
+*/
+void f();
diff --git a/test-files/old-tests/pre-post.xml b/test-files/old-tests/pre-post.xml
@@ -0,0 +1,20 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<mrdocs xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+       xsi:noNamespaceSchemaLocation="https://github.com/cppalliance/mrdocs/raw/develop/mrdocs.rnc">
+<namespace id="//////////////////////////8=">
+  <function name="f" id="s6nsa+zVhpzzrN+yUVPP5rvdXqs=">
+    <file path="pre-post.cpp" line="7"/>
+    <doc>
+      <pre>
+        <text>first precondition</text>
+      </pre>
+      <pre>
+        <text>second precondition</text>
+      </pre>
+      <post>
+        <text>first postcondition</text>
+      </post>
+    </doc>
+  </function>
+</namespace>
+</mrdocs>