chore: Dom tidy

Author: vinniefalco

include/mrdox/Support/Dom.hpp

@@ -19,7 +19,6 @@
 #include <string_view>
 #include <type_traits>
 #include <utility>
-
 #include <vector>
 
 namespace clang {
@@ -48,32 +47,51 @@ enum class Kind
 //
 //------------------------------------------------
 
-/** A type-erased object or array implementation.
+/** Reference-counting base class for dynamic types.
 */
 class MRDOX_DECL
     Any
 {
     std::atomic<std::size_t> mutable refs_ = 1;
 
 protected:
+    /** Destructor.
+    */
+    virtual ~Any() = 0;
+
+    /** Constructor.
+    */
     Any() noexcept;
+
+    /** Constructor.
+
+        The caller will have exclusive ownership
+        immediately after construction is complete.
+    */
     Any(Any const&) noexcept;
 
 public:
-    virtual ~Any() = 0;
-
+    /** Return a pointer with shared ownership.
+    */
     Any* addref() noexcept
     {
         ++refs_;
         return this;
     }
 
+    /** Return a pointer with shared ownership.
+    */
     Any const* addref() const noexcept
     {
         ++refs_;
         return this;
     }
 
+    /** Release shared ownership.
+
+        If this is the last remaining owner,
+        then this will be deleted.
+    */
     void release() const noexcept
     {
         if(--refs_ > 0)
@@ -92,16 +110,16 @@ auto create(Args&&... args);
 //
 //------------------------------------------------
 
-/** A pointer container for object or array.
+/** A pointer container for dynamic objects.
 */
-template<class T = Any>
-requires std::convertible_to<T*, Any*>
+template<class T>
 class Pointer
 {
     Any* any_;
 
+    static_assert(std::derived_from<T, Any>);
+
     template<class U>
-    requires std::convertible_to<U*, Any*>
     friend class Pointer;
 
     explicit
@@ -217,27 +235,102 @@ using ArrayPtr = Pointer<Array>;
 class MRDOX_DECL
     Object : public Any
 {
-    Object(Object const&);
+protected:
+    /** Constructor.
+
+        The newly constructed object will retain
+        a copy of the list of values in `other`.
+    */
+    Object(Object const& other);
 
 public:
+    /** The type of an element in this container.
+    */
     using value_type = std::pair<std::string, Value>;
+
+    /** The underlying, iterable range used by this container.
+    */
     using list_type = std::vector<value_type>;
 
+    /** Constructor.
+
+        Default-constructed objects are empty.
+    */
     Object() noexcept;
+
+    /** Constructor.
+
+        Upon construction, the object will retain
+        ownership of a shallow copy of the specified
+        list. In particular, dynamic objects will
+        be acquired with shared ownership.
+
+        @param list The initial list of values.
+    */
     explicit Object(list_type list);
+
+    /** Return an iterable range with the contents.
+    */
     list_type const& list() const noexcept;
+
+    /** Add elements to the container.
+
+        No checking is performed to prevent
+        the insertion of duplicate keys.
+    */
     void append(std::string_view key, Value value);
+
+    /** Add elements to the container.
+
+        No checking is performed to prevent
+        the insertion of duplicate keys.
+    */
     void append(std::initializer_list<value_type>);
+
+    /** Return a deep copy of the container.
+
+        In particular, dynamic objects will be
+        deeply copied; changes to the copy are
+        not reflected in the original.
+    */
     virtual Value copy() const;
+
+    /** Return true if the container is empty.
+    */
     virtual bool empty() const noexcept;
+
+    /** Return the value for a given key.
+
+        If the key does not exist, a null value
+        is returned.
+
+        @return The value, or null.
+
+        @param key The key.
+    */
     virtual Value get(std::string_view key) const;
+
+    /** Set or replace the value for a given key.
+
+        This function inserts a new key or changes
+        the value for the existing key if it is
+        already present.
+
+        @param key The key.
+
+        @param value The value to set.
+    */
     virtual void set(std::string_view key, Value value);
+
+    // VFALCO DEPRECATED (for duktape)
     virtual std::vector<std::string_view> props() const;
 
 private:
     list_type list_;
 };
 
+/** Alias for a pointer to an Object.
+*/
 using ObjectPtr = Pointer<Object>;
 
 /** Return a new object with a given list of properties.
@@ -260,14 +353,26 @@ class MRDOX_DECL
 {
     std::atomic<Object*> mutable p_ = nullptr;
 
+    /** Return the object.
+    */
     virtual ObjectPtr construct() const = 0;
 
 public:
-    LazyObject() noexcept;
+    /** Destructor.
+    */
     ~LazyObject() noexcept;
+
+    /** Constructor.
+    */
+    LazyObject() noexcept;
+
+    /** Return the object.
+    */
     ObjectPtr get() const;
 };
 
+/** Alias for a pointer to a LazyObject.
+*/
 using LazyObjectPtr = Pointer<LazyObject>;
 
 //------------------------------------------------
@@ -368,12 +473,32 @@ class MRDOX_DECL
     */
     Value copy() const;
 
+    /** Return the type of value contained.|
+    */
     dom::Kind kind() const noexcept;
+
+    /** Return true if this is null.
+    */
     bool isNull() const noexcept { return kind_ == Kind::Null; }
+
+    /** Return true if this is a boolean.
+    */
     bool isBool() const noexcept { return kind_ == Kind::Boolean; }
+
+    /** Return true if this is an integer.
+    */
     bool isInteger() const noexcept { return kind_ == Kind::Integer; }
+
+    /** Return true if this is a string.
+    */
     bool isString() const noexcept { return kind_ == Kind::String; }
+
+    /** Return true if this is an array.
+    */
     bool isArray() const noexcept { return kind_ == Kind::Array; }
+
+    /** Return true if this is an object.
+    */
     bool isObject() const noexcept
     {
         return
@@ -408,19 +533,33 @@ class MRDOX_DECL
         return arr_;
     }
 
-    ObjectPtr getObject() const noexcept;
+    /** Return the object if this is an object.
 
-    void swap(Value& other) noexcept;
+        @throw Error `! isObject()`
+    */
+    ObjectPtr
+    getObject() const;
+
+    /** Swap two values.
+    */
+    void
+    swap(Value& other) noexcept;
 
-    friend void swap(Value& v0, Value& v1) noexcept
+    /** Swap two values.
+    */
+    friend
+    void
+    swap(Value& v0, Value& v1) noexcept
     {
         v0.swap(v1);
     }
 };
 
+/** Return a non-empty string, or a null.
+*/
 inline
 Value
-nonEmptyString(
+stringOrNull(
     std::string_view s)
 {
     if(! s.empty())

source/Metadata/DomMetadata.cpp

@@ -262,9 +262,9 @@ class DomParam : public dom::Object
         Param const& I,
         Corpus const& corpus) noexcept
         : Object({
-            {"name", dom::nonEmptyString(I.Name)},
+            {"name", dom::stringOrNull(I.Name)},
             {"type", dom::create<DomTypeInfo>(I.Type, corpus)},
-            {"default", dom::nonEmptyString(I.Default)}
+            {"default", dom::stringOrNull(I.Default)}
         })
     {
     }
@@ -321,7 +321,7 @@ class DomTArg : public dom::Object
         TArg const& I,
         Corpus const& corpus)
         : Object({
-            {"value", dom::nonEmptyString(I.Value)}
+            {"value", dom::stringOrNull(I.Value)}
         })
     {
     }
@@ -448,7 +448,7 @@ DomTParam(
     Corpus const& corpus)
     : Object({
         {"kind", toString(I.Kind)},
-        {"name", dom::nonEmptyString(I.Name)},
+        {"name", dom::stringOrNull(I.Name)},
         {"is-pack", I.IsParameterPack},
         {"type", I.Kind == TParamKind::NonType ?
             dom::create<DomTypeInfo>(
@@ -837,7 +837,7 @@ construct() const
     {
         list.insert(list.end(), {
             { "type", dom::create<DomTypeInfo>(I_.Type, corpus_) },
-            { "default", dom::nonEmptyString(I_.Default) },
+            { "default", dom::stringOrNull(I_.Default) },
             { "isNodiscard", I_.specs.isNodiscard.get() },
             { "isDeprecated", I_.specs.isDeprecated.get() },
             { "hasNoUniqueAddress", I_.specs.hasNoUniqueAddress.get() }

source/Support/Dom.cpp

@@ -9,6 +9,7 @@
 //
 
 #include <mrdox/Support/Dom.hpp>
+#include <mrdox/Support/Error.hpp>
 
 namespace clang {
 namespace mrdox {
@@ -46,7 +47,14 @@ get(std::size_t) const
 
 Object::
 Object(
-    Object const&) = default;
+    Object const& other)
+{
+    // deep-copy the list
+    list_.reserve(other.list_.size());
+    for(auto const& kv : other.list_)
+        list_.emplace_back(
+            kv.first, kv.second.copy());
+}
 
 Object::
 Object() noexcept = default;
@@ -369,8 +377,9 @@ copy() const
         // we can just give the caller shared ownership.
         return *this;
     case Kind::Object:
-    case Kind::LazyObject:
         return obj_->copy();
+    case Kind::LazyObject:
+        return lazy_obj_->get()->copy();
     default:
         MRDOX_UNREACHABLE();
     }
@@ -413,14 +422,13 @@ isTruthy() const noexcept
 
 ObjectPtr
 Value::
-getObject() const noexcept
+getObject() const
 {
     if(kind_ == Kind::Object)
         return obj_;
     if(kind_ == Kind::LazyObject)
         return lazy_obj_->get();
-    MRDOX_ASSERT(kind_ == Kind::Object);
-    return obj_;
+    throw Error("not an Object");
 }
 
 void