Improve doxygen docs

README.md

@@ -1,7 +1,7 @@
 # Rapid YAML
 [![MIT Licensed](https://img.shields.io/badge/License-MIT-green.svg)](https://github.com/biojppm/rapidyaml/blob/master/LICENSE.txt)
 [![release](https://img.shields.io/github/v/release/biojppm/rapidyaml?color=g&include_prereleases&label=release%20&sort=semver)](https://github.com/biojppm/rapidyaml/releases)
-[![Documentation Status](https://readthedocs.org/projects/rapidyaml/badge/?version=latest)](https://rapidyaml.readthedocs.io/en/latest/?badge=latest)
+[![Documentation Status](https://readthedocs.org/projects/rapidyaml/badge/?version=latest)](https://rapidyaml.readthedocs.io/latest/?badge=latest)
 
 [![PyPI](https://img.shields.io/pypi/v/rapidyaml?color=g)](https://pypi.org/project/rapidyaml/)
 [![Gitter](https://badges.gitter.im/rapidyaml/community.svg)](https://gitter.im/rapidyaml/community)
@@ -51,7 +51,7 @@ ryml is written in C++11, and compiles cleanly with:
 * Intel Compiler
 
 ryml's API documentation is [available at
-ReadTheDocs](https://rapidyaml.readthedocs.io/en/latest/).
+ReadTheDocs](https://rapidyaml.readthedocs.io/latest/).
 
 ryml is [extensively unit-tested in Linux, Windows and
 MacOS](https://github.com/biojppm/rapidyaml/actions). The tests cover
@@ -239,7 +239,7 @@ level API for accessing and traversing the data tree.
 
 The following snippet is a very quick overview taken from quickstart
 sample ([see on
-doxygen](https://rapidyaml.readthedocs.io/en/latest/group__doc__quickstart.html)/[see
+doxygen](https://rapidyaml.readthedocs.io/latest/group__doc__quickstart.html)/[see
 on github](samples/quickstart.cpp). After cloning ryml
 (don't forget the `--recursive` flag for git), you can very easily
 build and run this executable using any of the build samples, eg the

doc/Doxyfile

@@ -957,6 +957,9 @@ INPUT                  = \
                          ../ext/c4core/src/c4/charconv.hpp \
                          ../ext/c4core/src/c4/format.hpp \
                          ../ext/c4core/src/c4/base64.hpp \
+                         ../ext/c4core/src/c4/std/string.hpp \
+                         ../ext/c4core/src/c4/std/string_view.hpp \
+                         ../ext/c4core/src/c4/std/vector.hpp \
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding. Doxygen uses
@@ -2495,6 +2498,8 @@ PREDEFINED = \
            "C4_MUST_BE_TRIVIAL_COPY(cls)= " \
            "C4_NO_INLINE= " \
            "C4_NO_UBSAN_IOVRFLW= " \
+           "C4_NODISCARD= " \
+           "C4_NORETURN= " \
            "C4_PURE= " \
            "C4_REQUIRE_RW(ty)=ty " \
            "C4_RESTRICT= " \

doc/doxy_main.md

@@ -10,25 +10,7 @@
     * @ref doc_node_type
     * @ref doc_tree
     * @ref doc_node_classes
-  * For serialization/deserialization:
-    * See @ref sample_scalar_types for when the type is scalar (a leaf node in the YAML tree, containing a string representation): 
-      * See examples on how to @ref sample_to_chars_scalar
-      * See examples on how to @ref sample_from_chars_scalar
-      * See the sample @ref sample::sample_user_scalar_types
-      * When serializing floating point values in C++ earlier than 17,
-        be aware that there may be a truncation of the precision with
-        the default to_chars implementation. To enforce a particular
-        precision, use for example @ref c4::fmt::real, or call
-        directly @ref c4::ftoa or @ref c4::dtoa, or any other method
-        (remember that ryml only stores the final string, so nothing
-        prevents you from creating it). See the relevant sample: @ref
-        sample::sample_float_precision.
-    * See @ref sample_container_types for when the type is a container (ie, a node which has children, which may themselves be containers).
-      * See the sample @ref sample::sample_user_container_types
-    * ryml does not use any STL containers internally, but it can be
-      used to serialize and deserialize these containers. See @ref
-      sample::sample_std_types for an example. See the header @ref
-      ryml_std.hpp and also the headers it includes.
+  * For serialization/deserialization, see @ref doc_serialization.
   * @ref doc_tag_utils - how to resolve tags
   * @ref doc_callbacks - how to set up error/allocation/deallocation
     callbacks either globally for the library, or for specific objects

doc/index.rst

@@ -12,17 +12,17 @@ and eat it too. Being rapid is definitely NOT the same as being
 unpractical, so ryml was written with easy AND efficient usage in
 mind.
 
-ryml is available as a single header file, or it can be used as a
-simple library with cmake -- both separately (ie
-build -> install -> ``find_package()``) or together with your project (ie with
+ryml is available both as a single header file, or as a simple library
+with cmake -- both separately (ie build -> install ->
+``find_package()``) or together with your project (ie with
 ``add_subdirectory()``). (See below for examples).
 
 ryml can use custom global and per-tree memory allocators and error
 handler callbacks, and is exception-agnostic. ryml provides a default
 implementation for the allocator (using ``std::malloc()``) and error
-handlers (using either exceptions, ``longjmp()`` or ``std::abort()``),
-but you can opt out of and provide your own memory allocation and
-error callbacks.
+handlers (using either exceptions or ``std::abort()``), but you can
+opt out the default implementation and provide your own memory
+allocation and error callbacks.
 
 For maximum portability, ryml does not depend on the STL, ie, it does
 not use any std container as part of its data structures. But ryml can
@@ -53,10 +53,78 @@ Table of contents
 .. toctree::
    :maxdepth: 3
 
-   ./sphinx_api_documentation
+   Doxygen docs <doxygen/index.html#http://>
    ./sphinx_quicklinks
    ./sphinx_is_it_rapid
    ./sphinx_yaml_standard
    ./sphinx_using
    ./sphinx_other_languages
    ./sphinx_alternative_libraries
+
+
+API teaser
+==========
+
+Here's a short teaser from the API quickstart overview (`see on
+doxygen <doxygen/group__doc__quickstart.html>`_ / `see full code on
+github
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/samples/quickstart.cpp>`_):
+
+.. code-block:: c++
+
+    // Parse YAML code in place, potentially mutating the buffer:
+    char yml_buf[] = "{foo: 1, bar: [2, 3], john: doe}";
+    ryml::Tree tree = ryml::parse_in_place(yml_buf);
+
+    // read from the tree:
+    ryml::NodeRef bar = tree["bar"];
+    CHECK(bar[0].val() == "2");
+    CHECK(bar[1].val() == "3");
+    CHECK(bar[0].val().str == yml_buf + 15); // points at the source buffer
+    CHECK(bar[1].val().str == yml_buf + 18);
+
+    // deserializing:
+    int bar0 = 0, bar1 = 0;
+    bar[0] >> bar0;
+    bar[1] >> bar1;
+    CHECK(bar0 == 2);
+    CHECK(bar1 == 3);
+
+    // serializing:
+    bar[0] << 10; // creates a string in the tree's arena
+    bar[1] << 11;
+    CHECK(bar[0].val() == "10");
+    CHECK(bar[1].val() == "11");
+
+    // add nodes
+    bar.append_child() << 12; // see also operator= (explanation below)
+    CHECK(bar[2].val() == "12");
+
+    // emit tree
+    // to std::string
+    CHECK(ryml::emitrs_yaml<std::string>(tree) == R"(foo: 1
+    bar:
+      - 10
+      - 11
+      - 12
+    john: doe
+    )");
+    std::cout << tree; // emit to stdout
+    ryml::emit_yaml(tree, stdout); // emit to file
+
+    // emit node
+    ryml::ConstNodeRef foo = tree["foo"];
+    // to std::string
+    CHECK(ryml::emitrs_yaml<std::string>(foo) == "foo: 1\n");
+    std::cout << foo; // emit node to stdout
+    ryml::emit_yaml(foo, stdout); // emit node to file
+
+
+.. note::
+   Please refer to the `Doxygen documentation
+   <./doxygen/index.html>`_, and read the `overview sample
+   <doxygen/group__doc__quickstart.html#ga1118e0fb55403d0e061626cf8a07cc0c>`_;
+   this will quickly teach you the basic concepts and caveats, which
+   will save you a lot of time.
+
+.. include:: sphinx_try_quickstart.rst

doc/sphinx_is_it_rapid.rst

@@ -38,9 +38,10 @@ against other libraries.
 Comparison with yaml-cpp
 ------------------------
 
-The first result set is for Windows, and is using a `appveyor.yml config
-file <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/appveyor.yml>`__. A comparison of these results is
-summarized on the table below:
+The first result set is for Windows, and is using a `appveyor.yml
+config file
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/appveyor.yml>`__. A
+comparison of these results is summarized on the table below:
 
 =========================== ===== ======= ==========
 Read rates (MB/s)           ryml  yamlcpp compared
@@ -49,12 +50,13 @@ appveyor / vs2017 / Release 101.5 5.3     20x / 5.2%
 appveyor / vs2017 / Debug   6.4   0.0844  76x / 1.3%
 =========================== ===== ======= ==========
 
-The next set of results is taken in Linux, comparing g++ 8.2 and clang++
-7.0.1 in parsing a YAML buffer from a `travis.yml config
-file <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/travis.yml>`__ or a JSON buffer from a
-`compile_commands.json file <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/compile_commands.json>`__. You
-can `see the full results
-here <https://github.com/biojppm/rapidyaml/blob/v0.5.0/results/parse.linux.i7_6800K.md>`__. Summarizing:
+The next set of results is taken in Linux, comparing g++ 8.2 and
+clang++ 7.0.1 in parsing a YAML buffer from a `travis.yml config file
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/travis.yml>`__
+or a JSON buffer from a `compile_commands.json file
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/compile_commands.json>`__. You
+can `see the full results here
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/results/parse.linux.i7_6800K.md>`__. Summarizing:
 
 ========================== ===== ======= ========
 Read rates (MB/s)          ryml  yamlcpp compared
@@ -86,13 +88,14 @@ Performance reading JSON
 So how does ryml compare against other JSON readers? Well, it may not
 be the fastest, but it's definitely ahead of the pack!
 
-The benchmark is the `same as above <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/bm_parse.cpp>`__, and it is
-reading the
-`compile_commands.json <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/compile_commands.json>`__, The
-``_arena`` suffix notes parsing a read-only buffer (so buffer copies are
-performed), while the ``_inplace`` suffix means that the source buffer
-can be parsed in place. The ``_reuse`` means the data tree and/or parser
-are reused on each benchmark repeat.
+The benchmark is the `same as above
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/bm_parse.cpp>`__,
+and it is reading the `compile_commands.json
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/cases/compile_commands.json>`__,
+The ``_arena`` suffix notes parsing a read-only buffer (so buffer
+copies are performed), while the ``_inplace`` suffix means that the
+source buffer can be parsed in place. The ``_reuse`` means the data
+tree and/or parser are reused on each benchmark repeat.
 
 Here’s what we get with g++ 8.2:
 
@@ -127,12 +130,14 @@ result).
 Performance emitting
 --------------------
 
-`Emitting benchmarks <https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/bm_emit.cpp>`__ also show similar speedups from
-the existing libraries, also anecdotally reported by some users `(eg,
-here’s a user reporting 25x speedup from
-yaml-cpp) <https://github.com/biojppm/rapidyaml/issues/28#issue-553855608>`__.
-Also, in some cases (eg, block folded multiline scalars), the speedup is
-as high as 200x (eg, 7.3MB/s -> 1.416MG/s).
+`Emitting benchmarks
+<https://github.com/biojppm/rapidyaml/blob/v0.5.0/bm/bm_emit.cpp>`__
+also show similar speedups from the existing libraries, also
+anecdotally reported by some users `(eg, here’s a user reporting 25x
+speedup from yaml-cpp)
+<https://github.com/biojppm/rapidyaml/issues/28#issue-553855608>`__.
+Also, in some cases (eg, block folded multiline scalars), the speedup
+is as high as 200x (eg, 7.3MB/s -> 1.416MG/s).
 
 
 Serialization performance

doc/sphinx_quicklinks.rst

@@ -9,6 +9,8 @@ Quick links
 
   * `Pull Requests <https://github.com/biojppm/rapidyaml/pull>`_
 
+  * `Kanban board <https://github.com/biojppm/rapidyaml/projects/1>`_
+
 * Latest release: `0.5.0 <https://github.com/biojppm/rapidyaml/releases/tag/v0.5.0>`_
 
   * `Release page [0.5.0] <https://github.com/biojppm/rapidyaml/releases/tag/v0.5.0>`_