Javadoc can be disengaged

fix cppalliance#71

.gitignore

@@ -7,4 +7,6 @@ build/
 temp/
 test/
 tests/decls/*.adoc
+tests/decls/*.bad.xml
 tests/javadoc/*.adoc
+tests/javadoc/*.bad.xml

include/mrdox/meta/Javadoc.hpp

@@ -289,14 +289,28 @@ struct Javadoc
 
     //--------------------------------------------
 
-    Javadoc() = default;
+    Javadoc() noexcept = default;
 
     /** Constructor
     */
     explicit
     Javadoc(
         List<Block> blocks);
 
+    /** Return true if this has a value.
+
+        A value will exist if a FullComment node
+        was encountered while visiting the AST.
+        After post-processing, it is possible for
+        this function to return `true` even if
+        there are no top-level blocks remaining.
+    */
+    bool
+    has_value() const noexcept
+    {
+        return has_value_;
+    }
+
     /** Return true if this is empty
     */
     bool
@@ -313,6 +327,14 @@ struct Javadoc
         return brief_.get();
     }
 
+    /** Set the object as having a value.
+    */
+    void
+    emplace() noexcept
+    {
+        has_value_ = true;
+    }
+
     /** Return the list of top level blocks.
     */
     List<Block> const&
@@ -424,6 +446,7 @@ struct Javadoc
 private:
     std::shared_ptr<Paragraph const> brief_;
     List<Block> blocks_;
+    bool has_value_ = false;
 };
 
 } // mrdox

source/lib/ast/BitcodeReader.cpp

@@ -791,6 +791,7 @@ readSubBlock(
         if(! rv)
             return rv.takeError();
         javadoc_ = rv.get();
+        javadoc_->emplace();
         if(auto err = readBlock(ID, javadoc_))
             return err;
         javadoc_ = nullptr;

source/lib/ast/BitcodeWriter.cpp

@@ -565,7 +565,7 @@ BitcodeWriter::
 emitBlock(
     Javadoc const& jd)
 {
-    if(! jd.empty())
+    if(jd.has_value())
     {
         StreamSubBlockGuard Block(Stream, BI_JAVADOC_BLOCK_ID);
         emitBlock(jd.getBlocks());

source/lib/ast/ParseJavadoc.cpp

@@ -152,6 +152,7 @@ class JavadocVisitor
     {
         visit(FC_);
 
+        // This must cause has_value() to return true
         return Javadoc(std::move(blocks_));
     }
 

source/lib/format/asciidoc/Asciidoc.cpp

@@ -240,7 +240,8 @@ writeRecord(
     openSection(I.Name);
 
     // Brief
-    writeBrief(I.javadoc.getBrief());
+    if(I.javadoc.has_value())
+        writeBrief(I.javadoc.getBrief());
 
     // Synopsis
     openSection("Synopsis");
@@ -270,7 +271,8 @@ writeRecord(
     closeSection();
 
     // Description
-    writeDescription(I.javadoc.getBlocks());
+    if(I.javadoc.has_value())
+        writeDescription(I.javadoc.getBlocks());
 
     // Nested Types
     writeNestedTypes(
@@ -612,8 +614,6 @@ Writer::
 writeDescription(
     List<Javadoc::Block> const& list)
 {
-    if(list.empty())
-        return;
     //os_ << '\n';
     openSection("Description");
     os_ << '\n';

source/lib/format/xml/XML.cpp

@@ -625,7 +625,7 @@ XMLGenerator::
 Writer::
 writeJavadoc(Javadoc const& jd)
 {
-    if(jd.empty())
+    if(! jd.has_value())
         return;
     openTag("doc");
     if(auto brief = jd.getBrief())

source/lib/meta/Javadoc.cpp

@@ -9,6 +9,7 @@
 // Official repository: https://github.com/cppalliance/mrdox
 //
 
+#include <mrdox/Debug.hpp>
 #include <mrdox/meta/Javadoc.hpp>
 #include <llvm/Support/Error.h>
 #include <llvm/Support/Path.h>
@@ -36,6 +37,7 @@ Javadoc::
 Javadoc(
     List<Block> blocks)
     : blocks_(std::move(blocks))
+    , has_value_(true)
 {
 }
 
@@ -56,6 +58,8 @@ Javadoc::
 operator==(
     Javadoc const& other) const noexcept
 {
+    if(has_value_ != other.has_value_)
+        return false;
     return blocks_ == other.blocks_;
 }
 
@@ -71,10 +75,19 @@ void
 Javadoc::
 merge(Javadoc&& other)
 {
+    if(! other.has_value())
+        return;
     // Unconditionally extend the blocks
     // since each decl may have a comment.
     if(other != *this)
+    {
+        has_value_ = true;
         append(blocks_, std::move(other.blocks_));
+    }
+    else
+    {
+        Assert(has_value_);
+    }
 }
 
 auto

source/tests/Tester.cpp

@@ -57,7 +57,7 @@ checkDirRecursively(
             path::extension(iter->path()).equals_insensitive(".cpp"))
         {
             outputPath = iter->path();
-            path::replace_extension(outputPath, "xml");
+            path::replace_extension(outputPath, "");
             workGroup.post(
                 [
                 this,
@@ -88,23 +88,26 @@ Tester::
 checkOneFile(
     Corpus const& corpus,
     llvm::StringRef inputPath,
-    llvm::SmallVectorImpl<char>& outputPathStr)
+    llvm::SmallString<340>& outputPath)
 {
     namespace fs = llvm::sys::fs;
     namespace path = llvm::sys::path;
 
-    llvm::StringRef outputPath;
-    outputPath = { outputPathStr.data(), outputPathStr.size() };
-
+    // build XML
     std::string xmlString;
     if(! xmlGen->buildString(xmlString, corpus, R_))
         return;
+
+    // check that the XML file exists and is valid
     std::error_code ec;
     fs::file_status stat;
-    ec = fs::status(outputPathStr, stat, false);
+    path::replace_extension(outputPath, "xml");
+    ec = fs::status(outputPath, stat, false);
     if(ec == std::errc::no_such_file_or_directory)
     {
-        // create the xml file and write to it
+        // If the file doesn't already exist, then
+        // create it and write the produced XML.
+        // This counts as a test failure.
         R_.reportTestFailure();
         llvm::raw_fd_ostream os(outputPath, ec, llvm::sys::fs::OF_None);
         if(R_.error(ec, "open the file '", outputPath, "' for writing"))
@@ -113,38 +116,41 @@ checkOneFile(
         if(R_.error(os.error(), "write the file '", outputPath, "'"))
             return;
         R_.reportError();
-        // keep going, to write the other files
+        R_.print("Wrote: file '", outputPath, "'");
+        return;
     }
-    else if(R_.error(ec, "call fs::status on '", outputPathStr, "'"))
+    if(R_.error(ec, "call fs::status on '", outputPath, "'"))
     {
         return;
     }
-    else if(stat.type() != fs::file_type::regular_file)
+    if(stat.type() != fs::file_type::regular_file)
     {
         R_.failed("Couldn't open '", outputPath, "' because it is not a regular file");
         return;
     }
-    else
     {
-        // perform test
-        auto bufferResult = llvm::MemoryBuffer::getFile(outputPath, false);
-        if(R_.error(bufferResult, "read the file '", outputPath, "'"))
+        // read the XML file to get the expected output
+        auto expectedXml = llvm::MemoryBuffer::getFile(outputPath, false);
+        if(R_.error(expectedXml, "read the file '", outputPath, "'"))
             return;
-        std::string_view good(bufferResult->get()->getBuffer());
-        if(xmlString != good)
+        if(xmlString != expectedXml->get()->getBuffer())
         {
-            R_.print(
-                "File: \"", inputPath, "\" failed.\n",
-                "Expected:\n",
-                good, "\n",
-                "Got:\n", xmlString, "\n");
+            // The output did not match, write the
+            // mismatched XML to a .bad.xml file
+            llvm::SmallString<340> badPath = outputPath;
+            path::replace_extension(badPath, ".bad.xml");
+            std::error_code ec;
+            llvm::raw_fd_ostream os(badPath, ec, llvm::sys::fs::OF_None);
+            if(! R_.error(ec, "open '", badPath, "' for writing"))
+                os << xmlString;
+            R_.print("Failed: \"", inputPath, "\"\n");
             R_.reportTestFailure();
         }
     }
+
     if(adocGen)
     {
-        path::replace_extension(outputPathStr, adocGen->extension());
-        outputPath = { outputPathStr.data(), outputPathStr.size() };
+        path::replace_extension(outputPath, adocGen->extension());
         adocGen->buildOne(outputPath, corpus, R_);
     }
 }

source/tests/Tester.hpp

@@ -47,7 +47,7 @@ class Tester
     checkOneFile(
         Corpus const& corpus,
         llvm::StringRef inputPath,
-        llvm::SmallVectorImpl<char>& outputPathStr);
+        llvm::SmallString<340>& outputPathStr);
 };
 
 } // mrdox

tests/javadoc/para-1.xml

@@ -14,9 +14,13 @@
   </function>
   <function name="f2" id="0MJUv5yGFR9nXWFLeYc+rjOY+iM=">
     <file path="para-1.cpp" line="10"/>
+    <doc>
+    </doc>
   </function>
   <function name="f3" id="khwJweIqd5FuWAg8T+l+GEljQVc=">
     <file path="para-1.cpp" line="17"/>
+    <doc>
+    </doc>
   </function>
   <function name="f4" id="5wJFEWD4Ev/Vf3QN/mFlKhtbC6E=">
     <file path="para-1.cpp" line="27"/>