Revise the contents of API References (#445)

* updated mkdocs-material & mkdocs-git-revision-date-localized-plugin

* updated copyright year in the license files

* restructured document pages

* revised documentation contents in the API references section

* organized structure of documentation contents in the API references section

* added top page & reordered documentation pages in the API references section

LICENSE.txt

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Kensuke Fukutani
+Copyright (c) 2023-2024 Kensuke Fukutani
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -184,7 +184,7 @@ Note that, since fkYAML deserializes scalars into native booleans or integers du
 
 This project is distributed under the [MIT License](https://opensource.org/license/mit/):  
 
-Copyright (c) 2023 Kensuke Fukutani  
+Copyright (c) 2023-2024 Kensuke Fukutani  
 
 Permission is hereby granted, free of charge, to any person obtaining a copy  
 of this software and associated documentation files (the "Software"), to deal  

docs/examples/ex_basic_node_constructor_7.cpp

@@ -10,7 +10,12 @@
 #include <fkYAML/node.hpp>
 
 int main() {
-    fkyaml::node n({true, false});
+    // create a sequence.
+    fkyaml::node n = {true, false};
     std::cout << n << std::endl;
+
+    // create a mapping.
+    fkyaml::node n2 = {{"foo", 1024}};
+    std::cout << n2 << std::endl;
     return 0;
 }

docs/examples/ex_basic_node_constructor_7.output

@@ -1,3 +1,5 @@
 - true
 - false
 
+foo: 1024
+

docs/examples/ex_basic_node_constructor_8.cpp → docs/examples/ex_basic_node_move_assignment_operator.cpp

@@ -10,10 +10,12 @@
 #include <fkYAML/node.hpp>
 
 int main() {
-    fkyaml::node n = {true, false};
-    std::cout << n << std::endl;
+    fkyaml::node n = true;
+    fkyaml::node n2 = 123;
+    n = std::move(n2);
+
+    std::cout << std::boolalpha << n.is_integer() << std::endl;
+    std::cout << n.get_value<std::int64_t>() << std::endl;
 
-    fkyaml::node n2 = {{"foo", 1024}};
-    std::cout << n2 << std::endl;
     return 0;
 }

docs/examples/ex_basic_node_move_assignment_operator.output

@@ -0,0 +1,2 @@
+true
+123

docs/mkdocs/Makefile

@@ -7,6 +7,13 @@ serve: build
 	venv/bin/mkdocs serve
 
 # install a Python virtual environment
+# requirements.txt was generated by running the following commands.
+# ```
+# python3 -m venv venv
+# venv/bin/pip install --upgrade pip
+# venv/bin/pip install mkdocs-material mkdocs-git-revision-date-localized-plugin
+# venv/bin/pip freeze > ./requirements.txt
+# ```
 install-venv: requirements.txt
 	python3 -m venv venv
 	venv/bin/pip install --upgrade pip

docs/mkdocs/docs/api/basic_node/add_anchor_name.md

@@ -15,7 +15,9 @@ If the basic_node has already had any anchor name, the new anchor name overwrite
 ***`anchor_name`*** [in]
 :   An anchor name. This should not be empty.
 
-???+ Example
+## **Examples**
+
+??? Example
 
     ```cpp
     --8<-- "examples/ex_basic_node_add_anchor_name.cpp:9"

docs/mkdocs/docs/api/basic_node/add_tag_name.md

@@ -15,7 +15,9 @@ If the basic_node has already had any tag name, the new tag name overwrites the
 ***`tag_name`*** [in]
 :   A tag name. This should not be empty.
 
-???+ Example
+## **Examples**
+
+??? Example
 
     ```cpp
     --8<-- "examples/ex_basic_node_add_tag_name.cpp:9"

docs/mkdocs/docs/api/basic_node/alias_of.md

@@ -7,23 +7,25 @@ static basic_node alias_of(const basic_node& anchor);
 ```
 
 Creates an alias YAML node from an anchor node.  
+If the given anchor node does not have any non-empty anchor name, an [`fkyaml::exception`](../exception/index.md) will be thrown.  
 
 ## **Parameters**
 
 ***anchor*** [in]
 :   A basic_node object with an anchor name.  
-    This node must have some anchor name.  
+    This node must have a non-empty anchor name.  
 
 ## **Return Value**
 
-An alias YAML node which is created from the given anchor node.  
-If the given anchor node does not have any non-empty anchor name, an [`fkyaml::exception`](../exception/index.md) will be thrown.  
+An alias node which refers to the given anchor node.  
 
 !!! Note
 
     If this API throws an exception, the internally stored YAML node value in the given anchor node stays intact.
 
-???+ Example
+## **Examples**
+
+??? Example
 
     ```cpp
     --8<-- "examples/ex_basic_node_alias_of.cpp:9"

docs/mkdocs/docs/api/basic_node/at.md

@@ -3,77 +3,61 @@
 # <small>fkyaml::basic_node::</small>at
 
 ```cpp
-template <
-    typename KeyType, detail::enable_if_t<
-                            detail::conjunction<
-                                detail::negation<detail::is_basic_node<KeyType>>,
-                                detail::is_node_compatible_type<basic_node, KeyType>>::value,
-                            int> = 0>
-basic_node& at(KeyType&& key); // (1)
-
-template <
-    typename KeyType, detail::enable_if_t<
-                            detail::conjunction<
-                                detail::negation<detail::is_basic_node<KeyType>>,
-                                detail::is_node_compatible_type<basic_node, KeyType>>::value,
-                            int> = 0>
-const basic_node& at(KeyType&& key) const; // (2)
-
-template <
-    typename KeyType, detail::enable_if_t<detail::is_basic_node<detail::remove_cvref_t<KeyType>>::value, int> = 0>
-basic_node& at(KeyType&& key); // (3)
-
-template <
-    typename KeyType, detail::enable_if_t<detail::is_basic_node<detail::remove_cvref_t<KeyType>>::value, int> = 0>
-const basic_node& at(KeyType&& key) const; // (4)
+// (1)
+template <typename KeyType>
+basic_node& at(KeyType&& key);
+
+template <typename KeyType>
+const basic_node& at(KeyType&& key) const;
+
+// (2)
+template <typename BasicNodeType>
+basic_node& at(BasicNodeType&& key);
+
+template <typename BasicNodeType>
+const basic_node& at(BasicNodeType&& key) const;
 ```
 
-Access to a YAML node element with either an index (for sequences) or a key (for mappings).  
-Before accessing the element, this function checks the bounds in the case of a sequence or the existence of a key in the case of a mapping.  
-This function therefore costs a bit more than [`basic_node::operator[]()`](operator[].md) function due to the extra checks.  
-Furthermore, this function may throw the following exceptions:
+Access to an element in a container node with either an index or key value.  
+This function must be called on a container node, or a [`fkyaml::type_error`](../exception/type_error.md) would be thrown.  
 
-* [`fkyaml::type_error`](../exception/type_error.md)
-    * if the queried node is neither a sequence nor a mapping, or
-    * if the queried node is a sequence but the given `key` is not an integer.
-* [`fkyaml::out_of_range`](../exception/out_of_range.md)
-    * if the given key does not exist in the queried mapping, or
-    * if the given index exceeds the size of the queried sequence.
+The input parameter `key` must be either a [`basic_node`](index.md) object or an object of a compatible type, i.e., a type with which a [`basic_node`](index.md) object can be constructible.  
+Note that the overload (1) internally constructs a temporal [`basic_node`](index.md) object.  
+So, if you use the same key multiple times, for example, in a for loop, consider creating a [`basic_node`](index.md) as a key first for better performance.
 
-## Overload (1), (2)  
+Furthermore, unlike the [`operator[]`](operator[].md), this function executes one of the following checks depending on the target node value type.  
 
-```cpp
-template <
-    typename KeyType, detail::enable_if_t<
-                            detail::conjunction<
-                                detail::negation<detail::is_basic_node<KeyType>>,
-                                detail::is_node_compatible_type<basic_node, KeyType>>::value,
-                            int> = 0>
-basic_node& at(KeyType&& key); // (1)
-
-template <
-    typename KeyType, detail::enable_if_t<
-                            detail::conjunction<
-                                detail::negation<detail::is_basic_node<KeyType>>,
-                                detail::is_node_compatible_type<basic_node, KeyType>>::value,
-                            int> = 0>
-const basic_node& at(KeyType&& key) const; // (2)
-```
+* For sequence nodes  
+    * Whether `key` is of an integeral type (e.g., `int`, `size_t`) or an integer node.  
+      If not, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.
+    * Whether the value of `key` is more than or equal to the size of the queried sequence.  
+      If not, a [`fkyaml::out_of_range`](../exception/out_of_range.md) will be thrown.
+* For mapping nodes
+    * Whether a given key exists in the target container.  
+      If not, [`fkyaml::out_of_range`](../exception/out_of_range.md) will be thrown.
+
+This function therefore costs a bit more than [`operator[]`](operator[].md) due to the above extra checks.  
 
-Accesses to an element in the YAML sequence/mapping node with the given key object of a compatible type with the [`basic_node`](index.md) class, i.e., a type with which a [`basic_node`](index.md) object is constructible.  
-These overloads internally construct a [`basic_node`](index.md) object with `key`.  
+## **Template Parameters**
 
+***KeyType***
+:   A compatible key type.
+
+***BasicNodeType***
+:   A basic_node template instance type.
+
+## **Parameters**
 
-### **Parameters**
+***`key`*** [in]
+:   A key to a target element in the sequence/mapping node.  
 
-***`index`*** [in]
-:   An index/key for an element in the YAML sequence/mapping node.  
+## **Return Value**
 
-### **Return Value**
+(Constant) reference to the node value which is associated with the given key.
 
-Reference, or constant reference, to the YAML node object associated with the given index/key.  
+## **Examples**
 
-???+ Example
+??? Example "Access an element with compatible keys"
 
     ```cpp
     --8<-- "examples/ex_basic_node_at_compatible_type.cpp:9"
@@ -84,37 +68,7 @@ Reference, or constant reference, to the YAML node object associated with the gi
     --8<-- "examples/ex_basic_node_at_compatible_type.output"
     ```
 
-## Overload (3), (4)
-
-```cpp
-template <
-    typename KeyType, detail::enable_if_t<detail::is_basic_node<detail::remove_cvref_t<KeyType>>::value, int> = 0>
-basic_node& at(KeyType&& key); // (3)
-
-template <
-    typename KeyType, detail::enable_if_t<detail::is_basic_node<detail::remove_cvref_t<KeyType>>::value, int> = 0>
-const basic_node& at(KeyType&& key) const; // (4)
-```
-
-Accesses to an element in the YAML sequence/mapping node with the given [`basic_node`](index.md) key object.  
-Unlike the overloads (1) and (2) above, these overloads do not internally construct a [`basic_node`](index.md) object.  
-So, these overloads works more effectively when some key objects are used multiple times, for instance, in a for-loop.  
-
-### **Template Parameters**
-
-***KeyType***
-:   A key type which is a kind of the [`basic_node`](index.md) template class.
-
-### **Parameters**
-
-***`key`*** [in]
-:   An index/key for an element in the YAML sequence/mapping node.
-
-### **Return Value**
-
-Reference, or constant reference, to the YAML node object associated with the given index/key.  
-
-???+ Example
+??? Example "Access an element with `basic_node` keys"
 
     ```cpp
     --8<-- "examples/ex_basic_node_at_basic_node.cpp:9"
@@ -128,8 +82,6 @@ Reference, or constant reference, to the YAML node object associated with the gi
 ## **See Also**
 
 * [basic_node](index.md)
-* [size](size.md)
-* [contains](contains.md)
 * [operator[]](operator[].md)
 * [operator<<](insertion_operator.md)
 * [out_of_range](../exception/out_of_range.md)

docs/mkdocs/docs/api/basic_node/begin.md

@@ -8,16 +8,18 @@ const_iterator begin() const;
 const_iterator cbegin() const;
 ```
 
-Returns an iterator to the first element of a container node.  
-Throws a [`fkyaml::type_error`](../exception/type_error.md) if a basic_node is neither a sequence nor mapping node.  
+Returns a (constant) iterator to the first element of a container node.  
+If a basic_node is neither a sequence nor mapping, a [`fkyaml::type_error`](../exception/type_error.md) will be thrown.  
 
 ![Image from https://en.cppreference.com/w/cpp/iterator/begin](../../img/range-begin-end.svg)
 
-### **Return Value**
+## **Return Value**
 
-An iterator to the first element of a container node.
+A (constant) iterator to the first element of a container node.
 
-???+ Example
+## **Examples**
+
+??? Example
 
     ```cpp
     --8<-- "examples/ex_basic_node_begin.cpp:9"

docs/mkdocs/docs/api/basic_node/boolean_type.md

@@ -6,17 +6,19 @@
 using boolean_type = BooleanType;
 ```
 
-The type used to store boolean node values.  
+The type used to store boolean values.  
 The YAML specification describes a boolean as a type which differentiates the following literals:
 
 * true, True, TRUE -> `true`
 * false, False, FALSE -> `false`
 
-To store boolean objects in [`basic_node`](index.md) class, the type is defined by the template parameter `BooleanType` which chooses the type to use for boolean objects.  
-If not explicitly specified, the default type `bool` will be chosen.  
-With the decided type, boolean objects are stored directly inside a [`basic_node`](index.md).  
+The actual type is defined by the template parameter `BooleanType`.  
+If not explicitly specified, the default type `bool` is defined.  
+With the decided type, boolean values are stored directly inside a [`basic_node`](index.md).  
 
-???+ Example
+## **Examples**
+
+??? Example
 
     ```cpp
     --8<-- "examples/ex_basic_node_boolean_type.cpp:9"