Javadoc is optional

Author: vinniefalco

include/mrdox/meta/Enum.hpp

@@ -70,6 +70,13 @@ struct EnumInfo : SymbolInfo
     // Indicates whether this enum is scoped (e.g. enum class).
     bool Scoped = false;
 
+    // Set to nonempty to the type when this is an explicitly typed enum. For
+    //   enum Foo : short { ... };
+    // this will be "short".
+    llvm::Optional<TypeInfo> BaseType;
+
+    llvm::SmallVector<EnumValueInfo, 4> Members; // List of enum members.
+
     //--------------------------------------------
 
     static constexpr InfoType type_id = InfoType::IT_enum;
@@ -87,13 +94,6 @@ struct EnumInfo : SymbolInfo
     }
 
     void merge(EnumInfo&& I);
-
-    // Set to nonempty to the type when this is an explicitly typed enum. For
-    //   enum Foo : short { ... };
-    // this will be "short".
-    llvm::Optional<TypeInfo> BaseType;
-
-    llvm::SmallVector<EnumValueInfo, 4> Members; // List of enum members.
 };
 
 } // mrdox

include/mrdox/meta/Info.hpp

@@ -15,6 +15,7 @@
 #include <mrdox/meta/Javadoc.hpp>
 #include <mrdox/meta/Reference.hpp>
 #include <mrdox/meta/Symbols.hpp>
+#include <llvm/ADT/Optional.h>
 #include <llvm/ADT/StringRef.h>
 #include <llvm/ADT/SmallString.h>
 #include <llvm/ADT/SmallVector.h>
@@ -47,7 +48,7 @@ struct Info
 
     /** The extracted javadoc for this declaration.
     */
-    Javadoc javadoc;
+    llvm::Optional<Javadoc> javadoc;
 
     //--------------------------------------------
 

include/mrdox/meta/Javadoc.hpp

@@ -297,20 +297,6 @@ struct Javadoc
     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
@@ -327,14 +313,6 @@ 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&
@@ -446,7 +424,6 @@ struct Javadoc
 private:
     std::shared_ptr<Paragraph const> brief_;
     List<Block> blocks_;
-    bool has_value_ = false;
 };
 
 } // mrdox

include/mrdox/meta/MemberType.hpp

@@ -24,6 +24,17 @@ struct MemberTypeInfo
     : FieldTypeInfo
     //, SymbolInfo
 {
+    // VFALCO This is public because 0 values in bitcode are not emitted...
+    // Access level associated with this info (public, protected, private, none).
+    // AS_public is set as default because the bitcode writer requires the enum
+    // with value 0 to be used as the default.
+    // (AS_public = 0, AS_protected = 1, AS_private = 2, AS_none = 3)
+    AccessSpecifier Access = AccessSpecifier::AS_public;
+
+    llvm::Optional<Javadoc> javadoc;
+
+    //--------------------------------------------
+
     MemberTypeInfo() = default;
 
     MemberTypeInfo(
@@ -43,15 +54,6 @@ struct MemberTypeInfo
             std::tie(Type, Name, Access, javadoc) ==
             std::tie(Other.Type, Other.Name, Other.Access, Other.javadoc);
     }
-
-    // VFALCO Why public?
-    // Access level associated with this info (public, protected, private, none).
-    // AS_public is set as default because the bitcode writer requires the enum
-    // with value 0 to be used as the default.
-    // (AS_public = 0, AS_protected = 1, AS_private = 2, AS_none = 3)
-    AccessSpecifier Access = AccessSpecifier::AS_public;
-
-    Javadoc javadoc;
 };
 
 } // mrdox

source/lib/ast/BitcodeReader.cpp

@@ -249,22 +249,19 @@ decodeRecord(
 
 //------------------------------------------------
 
-llvm::Expected<Javadoc*>
-getJavadoc(...)
+template<class T>
+llvm::Expected<llvm::Optional<Javadoc>*>
+getJavadoc(T I)
 {
-    return makeError("invalid type cannot contain Javadoc");
-}
-
-llvm::Expected<Javadoc*>
-getJavadoc(Info* I)
-{
-    return &I->javadoc;
-}
-
-llvm::Expected<Javadoc*>
-getJavadoc(MemberTypeInfo* I)
-{
-    return &I->javadoc;
+    if constexpr(std::is_pointer_v<T>)
+    {
+        using U = std::remove_pointer_t<T>;
+        if constexpr(std::derived_from<U, Info>)
+            return &I->javadoc;
+        else if constexpr(std::derived_from<U, MemberTypeInfo>)
+            return &I->javadoc;
+    }
+    return makeError("wrong type");
 }
 
 //------------------------------------------------
@@ -819,7 +816,7 @@ readSubBlock(
             return rv.takeError();
         javadoc_ = rv.get();
         javadoc_->emplace();
-        if(auto err = readBlock(ID, javadoc_))
+        if(auto err = readBlock(ID, &*javadoc_))
             return err;
         javadoc_ = nullptr;
         return llvm::Error::success();
@@ -832,7 +829,7 @@ readSubBlock(
             return err;
         if(! J.isTopLevel())
             return J.spliceIntoParent();
-        return J.spliceInto(javadoc_->getBlocks());
+        return J.spliceInto((*javadoc_)->getBlocks());
     }
 
     case BI_JAVADOC_NODE_BLOCK_ID:
@@ -1316,7 +1313,7 @@ parseRecord(
     Record const& R,
     unsigned ID,
     llvm::StringRef blob,
-    Javadoc* I)
+    llvm::Optional<Javadoc>* I)
 {
     // VFALCO Should never get here because this
     // only contains sub-blocks and no records (yet).

source/lib/ast/BitcodeReader.hpp

@@ -131,7 +131,7 @@ class BitcodeReader
     llvm::Error parseRecord(Record const& R, unsigned ID,
         llvm::StringRef Blob, TemplateParamInfo* I);
     llvm::Error parseRecord(Record const& R, unsigned ID,
-        llvm::StringRef Blob, Javadoc* I);
+        llvm::StringRef Blob, llvm::Optional<Javadoc>* I);
     llvm::Error parseRecord(Record const& R, unsigned ID,
         llvm::StringRef Blob, AnyNodeList* I);
     llvm::Error parseRecord(Record const& R, unsigned ID,
@@ -146,7 +146,7 @@ class BitcodeReader
     llvm::BitstreamCursor& Stream;
     llvm::Optional<llvm::BitstreamBlockInfo> BlockInfo;
     FieldId CurrentReferenceField;
-    Javadoc* javadoc_ = nullptr;
+    llvm::Optional<Javadoc>* javadoc_ = nullptr;
     AnyNodeList* nodes_ = nullptr;
 };
 

source/lib/ast/BitcodeWriter.cpp

@@ -417,7 +417,8 @@ emitBlock(
     emitRecord(I.Name, NAMESPACE_NAME);
     for (const auto& N : I.Namespace)
         emitBlock(N, FieldId::F_namespace);
-    emitBlock(I.javadoc);
+    if(I.javadoc)
+        emitBlock(*I.javadoc);
     for (const auto& C : I.Children.Namespaces)
         emitBlock(C, FieldId::F_child_namespace);
     for (const auto& C : I.Children.Records)
@@ -440,7 +441,8 @@ emitBlock(
     emitRecord(I.Name, RECORD_NAME);
     for (const auto& N : I.Namespace)
         emitBlock(N, FieldId::F_namespace);
-    emitBlock(I.javadoc);
+    if(I.javadoc)
+        emitBlock(*I.javadoc);
     if (I.DefLoc)
         emitRecord(*I.DefLoc, RECORD_DEFLOCATION);
     for (const auto& L : I.Loc)
@@ -494,7 +496,8 @@ emitBlock(
     emitRecord(I.Name, FUNCTION_NAME);
     for (const auto& N : I.Namespace)
         emitBlock(N, FieldId::F_namespace);
-    emitBlock(I.javadoc);
+    if(I.javadoc)
+        emitBlock(*I.javadoc);
     emitRecord(I.Access, FUNCTION_ACCESS);
     emitRecord(I.IsMethod, FUNCTION_IS_METHOD);
     emitRecord(I.specs.bits(), FUNCTION_BITS);
@@ -520,7 +523,8 @@ emitBlock(
     emitRecord(I.Name, ENUM_NAME);
     for (const auto& N : I.Namespace)
         emitBlock(N, FieldId::F_namespace);
-    emitBlock(I.javadoc);
+    if(I.javadoc)
+        emitBlock(*I.javadoc);
     if (I.DefLoc)
         emitRecord(*I.DefLoc, ENUM_DEFLOCATION);
     for (const auto& L : I.Loc)
@@ -562,7 +566,8 @@ emitBlock(
     emitRecord(T.Name, TYPEDEF_NAME);
     for (const auto& N : T.Namespace)
         emitBlock(N, FieldId::F_namespace);
-    emitBlock(T.javadoc);
+    if(T.javadoc)
+        emitBlock(*T.javadoc);
     if (T.DefLoc)
         emitRecord(*T.DefLoc, TYPEDEF_DEFLOCATION);
     emitRecord(T.IsUsing, TYPEDEF_IS_USING);
@@ -589,19 +594,19 @@ emitBlock(
     emitBlock(T.Type, FieldId::F_type);
     emitRecord(T.Name, MEMBER_TYPE_NAME);
     emitRecord(T.Access, MEMBER_TYPE_ACCESS);
-    emitBlock(T.javadoc);
+    if(T.javadoc)
+        emitBlock(*T.javadoc);
 }
 
 void
 BitcodeWriter::
 emitBlock(
     Javadoc const& jd)
 {
-    if(jd.has_value())
-    {
-        StreamSubBlockGuard Block(Stream, BI_JAVADOC_BLOCK_ID);
-        emitBlock(jd.getBlocks());
-    }
+    // If the optional<Javadoc> has a value then we
+    // always want to emit it, even if it is empty.
+    StreamSubBlockGuard Block(Stream, BI_JAVADOC_BLOCK_ID);
+    emitBlock(jd.getBlocks());
 }
 
 template<class T>

source/lib/ast/Serialize.cpp

@@ -293,7 +293,7 @@ getTemplateParams(
 static
 void
 parseJavadoc(
-    Javadoc& javadoc,
+    llvm::Optional<Javadoc>& javadoc,
     Decl const* D)
 {
     // VFALCO investigate whether we can use
@@ -303,7 +303,11 @@ parseJavadoc(
     if(RC)
     {
         RC->setAttached();
-        javadoc = parseJavadoc(RC, D->getASTContext(), D);
+        javadoc.emplace(parseJavadoc(RC, D->getASTContext(), D));
+    }
+    else
+    {
+        javadoc.reset();
     }
 }