Update documentation

Change-Id: I0173404d4d7720444488fe9fd8fc4346105604fb

Author: syyyr

Diff for: Doxyfile.in

@@ -5,4 +5,4 @@ INPUT = @doxy_main_page@ @PROJECT_SOURCE_DIR@ @PROJECT_BINARY_DIR@
 FILE_PATTERNS = *.hpp *.cpp *.md *.cmake
 RECURSIVE = YES
 EXTRACT_ANON_NSPACES = YES
-USE_MDFILE_AS_MAINPAGE = index.md
+USE_MDFILE_AS_MAINPAGE = README.md

Diff for: include/libyang-cpp/ChildInstantiables.hpp

@@ -38,7 +38,9 @@ class ChildInstanstiablesIterator {
 };
 
 /**
- * A collection that iterates over children of a node that can be instantiated, i.e. they can have a DataNode.
+ * @brief A collection that iterates over children of a schema node that can be instantiated, i.e. they can have a DataNode.
+ *
+ * Check out Module::childInstanstiables and SchemaNode::childInstanstiables for usage.
  */
 class ChildInstanstiables {
 public:

Diff for: include/libyang-cpp/Collection.hpp

@@ -83,6 +83,15 @@ class Iterator {
     void unregisterThis();
 };
 
+/**
+ * @brief A collection of SchemaNode or DataNode supporting multiple iteration types.
+ *
+ * For more info on iteration types, see these methods:
+ * - DataNode::childrenDfs
+ * - DataNode::siblings
+ * - SchemaNode::siblings
+ * - SchemaNode::childrenDfs
+ */
 template <typename NodeType, IterationType ITER_TYPE>
 class Collection {
 public:
@@ -118,6 +127,11 @@ class Collection {
     void throwIfInvalid() const;
 };
 
+/**
+ * @brief A collection for iterating over metadata of a DataNode.
+ *
+ * For more information, check DataNode::meta.
+ */
 class MetaCollection : public Collection<Meta, IterationType::Meta> {
 public:
     Iterator<Meta, IterationType::Meta> erase(Iterator<Meta, IterationType::Meta> what);

Diff for: include/libyang-cpp/Context.hpp

@@ -20,6 +20,9 @@
 
 struct ly_ctx;
 
+/**
+ * @brief The libyang-cpp namespace.
+ */
 namespace libyang {
 class Context;
 
@@ -28,6 +31,11 @@ using ContextDeleter = std::function<void(ly_ctx*)>;
 Context createUnmanagedContext(ly_ctx* ctx, ContextDeleter);
 ly_ctx* retrieveContext(Context ctx);
 
+/**
+ * @brief A structure containing a module as a string and its format.
+ *
+ * Used as the return value for module retrieval callback.
+ */
 struct ModuleInfo {
     std::string data;
     SchemaFormat format;
@@ -41,6 +49,11 @@ using ModuleCallback = std::optional<ModuleInfo>(const char* modName,
                                                  const char* submodName,
                                                  const char* submodRev);
 
+/**
+ * @brief Contains detailed libyang error.
+ *
+ * Wraps `ly_err_item`.
+ */
 struct ErrorInfo {
     bool operator==(const ErrorInfo& other) const = default;
     std::optional<std::string> appTag;

Diff for: include/libyang-cpp/DataNode.hpp

@@ -56,6 +56,8 @@ void validateAll(std::optional<libyang::DataNode>& node, const std::optional<Val
 
 /**
  * @brief Class representing a node in a libyang tree.
+ *
+ * Wraps `lyd_node`.
  */
 class DataNode {
 public:
@@ -147,6 +149,11 @@ class DataNode {
     std::shared_ptr<internal_refcount> m_refs;
 };
 
+/**
+ * @brief Represents a piece of metadata associated with a node.
+ *
+ * Represents a `lyd_meta` struct (but does not wrap it).
+ */
 class Meta {
 public:
     std::string name() const;
@@ -165,6 +172,8 @@ class Meta {
 
 /**
  * @brief Class representing a term node - leaf or leaf-list.
+ *
+ * Wraps `lyd_node_term`.
  */
 class DataNodeTerm : public DataNode {
 public:
@@ -178,11 +187,23 @@ class DataNodeTerm : public DataNode {
     using DataNode::DataNode;
 };
 
+/**
+ * @brief Contains a (possibly module-qualified) name of an opaque node.
+ *
+ * This is generic container of a prefix/module string and a name string.
+ *
+ * Wraps `ly_opaq_name`.
+ */
 struct OpaqueName {
     std::optional<std::string_view> prefix;
     std::string_view name;
 };
 
+/**
+ * @brief Class representing an opaque node.
+ *
+ * Wraps `lyd_node_opaq`.
+ */
 class DataNodeOpaque : public DataNode {
 public:
     OpaqueName name() const;
@@ -205,21 +226,28 @@ class DataNodeAny : public DataNode {
     using DataNode::DataNode;
 };
 
+/**
+ * @brief Represents a YANG operation data tree.
+ *
+ * Used as the return value of `DataNode::parseOp` and Context::parseOp.
+ */
 struct ParsedOp {
     std::optional<libyang::DataNode> tree;
     std::optional<libyang::DataNode> op;
 };
 
 /**
- * This struct represents the return value for newPath2.
+ * @brief This struct represents the return value for newPath2.
  */
 struct CreatedNodes {
     /**
-     * Contains the first created parent. Will be the same as `createdNode` if only one was created.
+     * @brief Contains the first created parent.
+     *
+     * Will be the same as `createdNode` if only one node was created.
      */
     std::optional<DataNode> createdParent;
     /**
-     * Contains the node specified by `path` from the original newPath2 call.
+     * @brief Contains the node specified by `path` from the original newPath2 call.
      */
     std::optional<DataNode> createdNode;
 };

Diff for: include/libyang-cpp/Module.hpp

@@ -25,6 +25,11 @@ class ChildInstanstiables;
 class Identity;
 class SchemaNode;
 
+/**
+ * @brief Represents a feature of a module.
+ *
+ * Wraps `lysp_feature`.
+ */
 class Feature {
 public:
     std::string_view name() const;

Diff for: include/libyang-cpp/SchemaNode.hpp

@@ -41,6 +41,8 @@ class Iterator;
 
 /**
  * @brief Class representing a schema definition of a node.
+ *
+ * Wraps `lysc_node`.
  */
 class SchemaNode {
 public:
@@ -51,6 +53,9 @@ class SchemaNode {
     Status status() const;
     Config config() const;
     NodeType nodeType() const;
+    // It is possible to cast SchemaNode to another type via the following methods. The types are children classes of
+    // SchemaNode. No problems with slicing can occur, because these types are value-based and aren't constructible
+    // drectly by the user.
     // TODO: turn these into a templated `as<>` method.
     Container asContainer() const;
     Leaf asLeaf() const;
@@ -78,6 +83,9 @@ class SchemaNode {
     SchemaNode(const lysc_node* node, std::nullptr_t);
 };
 
+/**
+ * @brief Class representing a schema definition of a `container` node.
+ */
 class Container : public SchemaNode {
 public:
     bool isPresence() const;
@@ -87,6 +95,11 @@ class Container : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of a `leaf` node.
+ *
+ * Wraps `lysc_node_leaf`.
+ */
 class Leaf : public SchemaNode {
 public:
     bool isKey() const;
@@ -99,6 +112,11 @@ class Leaf : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of a `leaflist` node.
+ *
+ * Wraps `lysc_node_leaflist`.
+ */
 class LeafList : public SchemaNode {
 public:
     Type valueType() const;
@@ -109,6 +127,11 @@ class LeafList : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of a `list` node.
+ *
+ * Wraps `lysc_node_list`.
+ */
 class List : public SchemaNode {
 public:
     std::vector<Leaf> keys() const;
@@ -118,6 +141,11 @@ class List : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of an `input` node of an RPC/action node.
+ *
+ * Wraps `lysc_node_action_inout`.
+ */
 class ActionRpcInput : public SchemaNode {
 public:
     friend ActionRpc;
@@ -126,6 +154,11 @@ class ActionRpcInput : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of an `output` node of an RPC/action node.
+ *
+ * Wraps `lysc_node_action_inout`.
+ */
 class ActionRpcOutput : public SchemaNode {
 public:
     friend ActionRpc;
@@ -134,6 +167,11 @@ class ActionRpcOutput : public SchemaNode {
     using SchemaNode::SchemaNode;
 };
 
+/**
+ * @brief Class representing a schema definition of a `action` or `rpc` node.
+ *
+ * Wraps `lysc_node_action`.
+ */
 class ActionRpc : public SchemaNode {
 public:
     ActionRpcInput input() const;

Diff for: include/libyang-cpp/Set.hpp

@@ -60,6 +60,9 @@ class SetIterator {
     const Set<NodeType>* m_set;
 };
 
+/**
+ * @brief An array-like collection of nodes.
+ */
 template <typename NodeType>
 class Set {
 public:

Diff for: include/libyang-cpp/Type.hpp

@@ -23,6 +23,11 @@ namespace libyang {
 class Leaf;
 class LeafList;
 class Module;
+/**
+ * @brief Contains representations of `leaf` schema data types.
+ *
+ * TODO: add examples/tutorials on how to work datatypes in libyang-cpp
+ */
 namespace types {
 class Bits;
 class Enumeration;
@@ -31,7 +36,9 @@ class LeafRef;
 class Union;
 }
 /**
- * @brief Contains information about leaf's type.
+ * @brief Contains information about a leaf's type.
+ *
+ * Wraps `lysc_type`.
  */
 class Type {
 public:
@@ -62,6 +69,11 @@ class Type {
     Type(const lysc_type* type, const lysp_type* typeParsed, std::shared_ptr<ly_ctx> ctx);
 };
 
+/**
+ * @brief Contains information about an identity.
+ *
+ * Wraps `lysc_ident`.
+ */
 class Identity {
 public:
     friend types::IdentityRef;
@@ -77,10 +89,20 @@ class Identity {
 };
 
 namespace types {
+/**
+ * @brief Contains information about the `enumeration` leaf type.
+ *
+ * Wraps `lysc_type_enum`.
+ */
 class Enumeration : public Type {
 public:
     friend Type;
 
+    /**
+     * @brief Contains information about an enum from an `enumeration` leaf type.
+     *
+     * Wraps `lysc_type_bitenum_item`.
+     */
     struct Enum {
         auto operator<=>(const Enum& other) const = default;
         std::string name;
@@ -93,6 +115,11 @@ class Enumeration : public Type {
     using Type::Type;
 };
 
+/**
+ * @brief Contains information about the `identityref` leaf type.
+ *
+ * Wraps `lysc_type_identityref`.
+ */
 class IdentityRef : public Type {
 public:
     friend Type;
@@ -103,6 +130,9 @@ class IdentityRef : public Type {
     using Type::Type;
 };
 
+/**
+ * @brief Contains information about the `leafref` leaf type.
+ */
 class LeafRef : public Type {
 public:
     friend Type;
@@ -114,8 +144,18 @@ class LeafRef : public Type {
     using Type::Type;
 };
 
+/**
+ * @brief Contains information about the `bits` leaf type.
+ *
+ * Wraps `lysc_type_bits`.
+ */
 class Bits : public Type {
 public:
+    /**
+     * @brief Contains information about a specific bit from a `bits` leaf type.
+     *
+     * Wraps `lysc_type_bitenum_item`.
+     */
     struct Bit {
         auto operator<=>(const Bit& other) const = default;
         std::string name;
@@ -130,6 +170,11 @@ class Bits : public Type {
     using Type::Type;
 };
 
+/**
+ * @brief Contains information about the `union` leaf type.
+ *
+ * Wraps `lysc_type_union`.
+ */
 class Union : public Type {
 public:
     std::vector<Type> types() const;