refactor(Corpus): enforce non-optional polymorphic types

Ensure optional polymorphic types are only used for members that are really optional in terms of application logic. Otherwise, we only make them polymorphic objects that cannot be empty and give them reasonable defaults among the derived types in that type family.

Author: alandefreitas

include/mrdocs/Metadata/Info/Concept.hpp

@@ -12,8 +12,8 @@
 #define MRDOCS_API_METADATA_INFO_CONCEPT_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/ADT/Optional.hpp>
+#include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/Metadata/Expression.hpp>
 #include <mrdocs/Metadata/Info.hpp>
 #include <mrdocs/Metadata/Info/Source.hpp>

include/mrdocs/Metadata/Info/Enum.hpp

@@ -24,17 +24,32 @@ namespace clang::mrdocs {
 struct EnumInfo final
     : InfoCommonBase<InfoKind::Enum>
 {
-    // Indicates whether this enum is scoped (e.g. enum class).
+    /** Indicates whether this enum is scoped (e.g. enum class).
+
+        If true, the enumerators are accessed with the scope resolution
+        operator (e.g. EnumName::Enumerator).
+
+        If false, the enumerators are accessed directly (e.g. Enumerator)
+        in the parent context.
+    */
     bool Scoped = false;
 
-    // Set too nonempty to the type when this is an explicitly typed enum. For
-    //   enum Foo : short { ... };
-    // this will be "short".
+    /** The underlying type of this enum, if explicitly specified.
+
+        If not specified, the underlying type is an implementation-defined
+        integral type that can represent all the enumerator values defined in
+        the enumeration.
+
+        For `enum Foo : short { ... };` this will be represent `short`.
+    */
     Optional<Polymorphic<TypeInfo>> UnderlyingType = std::nullopt;
 
     /** The members of this scope.
 
-        All members are enum constants;
+        All members are enum constants.
+
+        Enum constants are independent symbol types that
+        can be documented separately.
     */
     std::vector<SymbolID> Constants;
 

include/mrdocs/Metadata/Info/Friend.hpp

@@ -21,7 +21,13 @@ namespace clang::mrdocs {
 
     - Friendship is not transitive
     - Friendship is not inherited
-    - Access specifiers have no effect on the meaning of friend declarations
+    - Access specifiers do not affect the meaning of friend declarations
+
+    The friends of a record are stored directly in the record's metadata.
+
+    If the friend declaration is documented, the documentation is
+    stored in the befriended symbol's metadata rather than in the
+    relationship.
 */
 struct FriendInfo final
 {
@@ -30,6 +36,8 @@ struct FriendInfo final
     SymbolID id = SymbolID::invalid;
 
     /** Befriended type.
+
+        This member is nullable and only used when befriending a type.
     */
     Optional<Polymorphic<TypeInfo>> Type = std::nullopt;
 };

include/mrdocs/Metadata/Info/Function.hpp

@@ -30,8 +30,15 @@ namespace clang::mrdocs {
 struct FunctionInfo final
     : InfoCommonBase<InfoKind::Function>
 {
-    /// Info about the return type of this function.
-    Optional<Polymorphic<TypeInfo>> ReturnType = std::nullopt;
+    /** Info about the return type of this function.
+
+        If the function has a deduced return type, this contains
+        `auto` to indicate that.
+
+        By default, we also use `auto` in the member to indicate
+        an unknown return type.
+     */
+    Polymorphic<TypeInfo> ReturnType = Polymorphic<TypeInfo>(AutoTypeInfo{});
 
     /// List of parameters.
     std::vector<Param> Params;

include/mrdocs/Metadata/Info/Guide.hpp

@@ -12,8 +12,8 @@
 #define MRDOCS_API_METADATA_INFO_GUIDE_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/ADT/Optional.hpp>
+#include <mrdocs/ADT/Polymorphic.hpp>
 #include <mrdocs/Metadata/Info.hpp>
 #include <mrdocs/Metadata/Info/Function.hpp>
 #include <mrdocs/Metadata/Info/Source.hpp>
@@ -32,7 +32,7 @@ struct GuideInfo final
 
         This is always a SpecializationTypeInfo.
     */
-    Optional<Polymorphic<TypeInfo>> Deduced = std::nullopt;
+    Polymorphic<TypeInfo> Deduced = Polymorphic<TypeInfo>(AutoTypeInfo{});
 
     /** Template head, if any.
     */

include/mrdocs/Metadata/Info/NamespaceAlias.hpp

@@ -28,7 +28,7 @@ struct NamespaceAliasInfo final
         This is another namespace that might or might
         not be in the same project.
      */
-    Optional<Polymorphic<NameInfo>> AliasedSymbol;
+    IdentifierNameInfo AliasedSymbol;
 
     //--------------------------------------------
 

include/mrdocs/Metadata/Info/Overloads.hpp

@@ -31,8 +31,13 @@ struct OverloadsInfo final
     /// The members of the overload set.
     std::vector<SymbolID> Members;
 
-    /// Info about the return type of this function.
-    Optional<Polymorphic<TypeInfo>> ReturnType = std::nullopt;
+    /** Info about the return type of these function overloads.
+
+        If all overloads have the same return type, this contains
+        that type. Otherwise, it contains `auto` to indicate that
+        the return type varies according to the parameters.
+     */
+    Polymorphic<TypeInfo> ReturnType = Polymorphic<TypeInfo>(AutoTypeInfo{});
 
     //--------------------------------------------
 

include/mrdocs/Metadata/Info/Param.hpp

@@ -27,7 +27,7 @@ struct Param final
 {
     /** The type of this parameter
      */
-    Optional<Polymorphic<TypeInfo>> Type = std::nullopt;
+    Polymorphic<TypeInfo> Type = Polymorphic<TypeInfo>(AutoTypeInfo{});
 
     /** The parameter name.
      */

include/mrdocs/Metadata/Info/RecordBase.hpp

@@ -22,11 +22,23 @@ namespace clang::mrdocs {
 */
 struct BaseInfo
 {
-    Optional<Polymorphic<TypeInfo>> Type;
+    /** The base type.
+
+        This is typically a `NamedTypeInfo` that refers to a
+        `RecordInfo`, but it could also be a more complex type
+        such as a `decltype`.
+     */
+    Polymorphic<TypeInfo> Type;
+
+    /** The access specifier for the base.
+     */
     AccessKind Access = AccessKind::Public;
+
+    /** Whether the base is virtual.
+     */
     bool IsVirtual = false;
 
-    BaseInfo() = default;
+    BaseInfo() = delete;
 
     BaseInfo(
         Polymorphic<TypeInfo>&& type,

include/mrdocs/Metadata/Info/Source.hpp

@@ -14,9 +14,9 @@
 #define MRDOCS_API_METADATA_INFO_SOURCE_HPP
 
 #include <mrdocs/Platform.hpp>
-#include <mrdocs/Metadata/Info/Location.hpp>
 #include <mrdocs/ADT/Optional.hpp>
 #include <mrdocs/Dom.hpp>
+#include <mrdocs/Metadata/Info/Location.hpp>
 #include <string>
 
 namespace clang::mrdocs {