refactor: custom ValueFrom for Info types

Author: alandefreitas

include/mrdocs/Corpus.hpp

@@ -119,8 +119,7 @@ class MRDOCS_VISIBLE
     template<class T = Info>
     requires std::derived_from<T, Info>
     T const&
-    get(
-        SymbolID const& id) const noexcept;
+    get(SymbolID const& id) const noexcept;
 
     /** Return the metadata for the global namespace.
 
@@ -160,18 +159,23 @@ class MRDOCS_VISIBLE
         }
     }
 
-    /** Visit the function members of specified Info.
+    /** Visit the member overloads of specified ScopeInfo.
 
-        This function iterates the members of the specified
-        ScopeInfo `S`. For each member associated with a
-        function with the same name as the member, the
-        function object `f` is invoked with the member
+        This function iterates the members of the
+        specified ScopeInfo `S`.
+
+        For each member in the scope, we check
+        if the member is a function with overloads.
+
+        If the member is a function with overloads,
+        we create an @ref OverloadSet object and invoke
+        the function object `f` with the @ref OverloadSet
         as the first argument, followed by `args...`.
 
-        When there are more than one member function
-        with the same name, the function object `f` is
-        invoked with an @ref OverloadSet as the first
-        argument, followed by `args...`.
+        If the member is not a function with overloads,
+        we invoke the function object `f` with the @ref Info
+        member as the first argument, followed by `args...`.
+
     */
     template <class F, class... Args>
     void traverseOverloads(
@@ -230,6 +234,7 @@ traverseOverloads(
     ScopeInfo const& S,
     F&& f, Args&&... args) const
 {
+    MRDOCS_ASSERT(S.Members.empty() == S.Lookups.empty());
     for(const SymbolID& id : S.Members)
     {
         const Info& member = get(id);
@@ -244,8 +249,10 @@ traverseOverloads(
                 return get(elem).isFunction();
             #endif
             });
-        if(lookup.size() == 1 ||
-            first_func == lookup.end())
+        bool const nonOverloadedFunction = lookup.size() == 1;
+        bool const notFunction = first_func == lookup.end();
+        if(nonOverloadedFunction ||
+           notFunction)
         {
             visit(member, std::forward<F>(f),
                 std::forward<Args>(args)...);

include/mrdocs/Dom/Value.hpp

@@ -113,14 +113,6 @@ class MRDOCS_DECL
 
     Value(char c) noexcept : Value(std::string_view(&c, 1)) {}
 
-    template<class Enum>
-    requires
-        std::is_enum_v<Enum> &&
-        (!std::same_as<Enum, dom::Kind>)
-    Value(Enum v) noexcept
-        : Value(static_cast<std::underlying_type_t<Enum>>(v))
-    {}
-
     template<std::size_t N>
     Value(char const(&sz)[N])
         : Value(String(sz))
@@ -800,6 +792,45 @@ ValueFrom(T&& t)
     return v;
 }
 
+/** Convert an object of type `T` to @ref dom::Value with a context
+
+    This function attempts to convert an object
+    of type `T` to @ref dom::Value using
+
+    @li a user-provided overload of `tag_invoke`.
+
+    @li one of @ref dom::Value's constructors,
+
+    Conversion of other types is done by calling an overload of `tag_invoke`
+    found by argument-dependent lookup. Its signature should be similar to:
+
+    @code
+    void tag_invoke( ValueFromTag, dom::Value&, T );
+    @endcode
+
+    @par Exception Safety
+    Strong guarantee.
+
+    @tparam T The type of the object to convert.
+
+    @param t The object to convert.
+
+    @return @ref dom::Value out parameter.
+
+    @see @ref dom::ValueFromTag,
+    <a href="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2019/p1895r0.pdf">
+        tag_invoke: A general pattern for supporting customisable functions</a>
+*/
+template <class T, class Context>
+requires HasValueFrom<T, Context>
+Value
+ValueFrom(T&& t, Context const& ctx)
+{
+    dom::Value v;
+    ValueFrom(static_cast<T&&>(t), ctx, v);
+    return v;
+}
+
 } // dom
 
 template <std::convertible_to<std::string_view> SV>

include/mrdocs/Metadata/Function.hpp

@@ -67,6 +67,19 @@ enum class FunctionClass
 
 MRDOCS_DECL dom::String toString(FunctionClass kind) noexcept;
 
+/** Return the FunctionClass from a @ref dom::Value string.
+ */
+inline
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    FunctionClass kind)
+{
+    v = toString(kind);
+}
+
+
 // KRYSTIAN TODO: attributes (nodiscard, deprecated, and carries_dependency)
 // KRYSTIAN TODO: flag to indicate whether this is a function parameter pack
 /** Represents a single function parameter */
@@ -97,6 +110,16 @@ struct Param
     }
 };
 
+/** Return the Param as a @ref dom::Value object.
+ */
+MRDOCS_DECL
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    Param const& p,
+    DomCorpus const* domCorpus);
+
 // TODO: Expand to allow for documenting templating and default args.
 // Info for functions.
 struct FunctionInfo

include/mrdocs/Metadata/Info.hpp

@@ -47,6 +47,18 @@ MRDOCS_DECL
 dom::String
 toString(InfoKind kind) noexcept;
 
+/** Return the InfoKind from a @ref dom::Value string.
+ */
+inline
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    InfoKind kind)
+{
+    v = toString(kind);
+}
+
 /** Base class with common properties of all symbols
 */
 struct MRDOCS_VISIBLE
@@ -203,6 +215,17 @@ concept InfoParent = requires(T const& t) {
     requires std::convertible_to<std::ranges::range_value_t<decltype(t.Members)>, SymbolID const&>;
 };
 
+/** Return the Info to a @ref dom::Value object.
+ */
+MRDOCS_DECL
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    Info const& I,
+    DomCorpus const* domCorpus);
+
+
 } // mrdocs
 } // clang
 

include/mrdocs/Metadata/Interface.hpp

@@ -24,51 +24,123 @@ namespace clang {
 namespace mrdocs {
 
 /** A group of children that have the same access specifier.
+
+    This struct represents a collection of symbols that share
+    the same access specifier within a scope.
+
+    It includes one vector for each info type,
+    and individual vectors for static functions, types,
+    and overloads.
+
+    The tranche is not part of the Corpus. It is a temporary
+    structure generated to aggregate the symbols of a scope. This
+    structure is provided to the user via the DOM.
 */
 struct Tranche
 {
     #define INFO(Type) std::vector<SymbolID> Type;
     #include <mrdocs/Metadata/InfoNodesPascalPlural.inc>
 
+    /// The types with the same access specifier in a scope.
     std::vector<SymbolID> Types;
+
+    /// The static functions with the same access specifier in a scope.
     std::vector<SymbolID> StaticFunctions;
 
+    /// The overloads with the same access specifier in a scope.
     ScopeInfo Overloads;
+
+    /// The static overloads with the same access specifier in a scope.
     ScopeInfo StaticOverloads;
 };
 
+/** Return a tranche representing the members of a namespace.
+
+    @return The tranche.
+
+    @param Derived The namespace to build the tranche for.
+
+    @param corpus The complete metadata.
+*/
+MRDOCS_DECL
+Tranche
+makeTranche(
+    NamespaceInfo const& Namespace,
+    Corpus const& corpus);
+
+/** Return the Tranche as a @ref dom::Value object.
+ */
+MRDOCS_DECL
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    std::shared_ptr<Tranche> const& sp,
+    DomCorpus const* domCorpus);
+
 /** The aggregated interface for a given struct, class, or union.
+
+    This class represents the public, protected, and private
+    interfaces of a record. It is used to generate the
+    "interface" value of the DOM for symbols that represent
+    records or namespaces.
+
+    The interface is not part of the Corpus. It is a temporary
+    structure generated to aggregate the symbols of a record.
+    This structure is provided to the user via the DOM.
+
+    While the members of a Namespace are directly represented
+    with a Tranche, the members of a Record are represented
+    with an Interface.
+
 */
 class Interface
 {
 public:
+    /// The corpus containing the complete metadata.
     Corpus const& corpus;
 
     /** The aggregated public interfaces.
-    */
+
+        This tranche contains all public members of a record
+        or namespace.
+
+     */
     std::shared_ptr<Tranche> Public;
 
     /** The aggregated protected interfaces.
-    */
+
+        This tranche contains all protected members of a record
+        or namespace.
+
+     */
     std::shared_ptr<Tranche> Protected;
 
     /** The aggregated private interfaces.
-    */
+
+        This tranche contains all private members of a record
+        or namespace.
+
+     */
     std::shared_ptr<Tranche> Private;
 
+    /** Creates an Interface object for a given record.
+
+        @param I The record to create the interface for.
+        @param corpus The complete metadata.
+        @return The interface.
+     */
     MRDOCS_DECL
     friend
     Interface
     makeInterface(
-        RecordInfo const& Derived,
+        RecordInfo const& I,
         Corpus const& corpus);
 
 private:
     explicit Interface(Corpus const&) noexcept;
 };
 
-//------------------------------------------------
-
 /** Return the composite interface for a record.
 
     @return The interface.
@@ -82,22 +154,18 @@ class Interface
 MRDOCS_DECL
 Interface
 makeInterface(
-    RecordInfo const& Derived,
+    RecordInfo const& I,
     Corpus const& corpus);
 
-/** Return a tranche representing the members of a namespace.
-
-    @return The tranche.
-
-    @param Derived The namespace to build the tranche for.
-
-    @param corpus The complete metadata.
-*/
+/** Return the Tranche as a @ref dom::Value object.
+ */
 MRDOCS_DECL
-Tranche
-makeTranche(
-    NamespaceInfo const& Namespace,
-    Corpus const& corpus);
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    std::shared_ptr<Interface> const& sp,
+    DomCorpus const* domCorpus);
 
 } // mrdocs
 } // clang

include/mrdocs/Metadata/Javadoc.hpp

@@ -1019,6 +1019,16 @@ class MRDOCS_DECL
     doc::List<doc::Block> blocks_;
 };
 
+/** Return the Javadoc as a @ref dom::Value.
+ */
+MRDOCS_DECL
+void
+tag_invoke(
+    dom::ValueFromTag,
+    dom::Value& v,
+    Javadoc const& I,
+    DomCorpus const* domCorpus);
+
 } // mrdocs
 } // clang