Merge pull request #2312 from nlohmann/docs

Update documentation
nlohmann · Jul 26, 2020 · 67ed63b · 67ed63b
2 parents 808aca4 + a34070d
commit 67ed63b
Show file tree

Hide file tree

Showing 21 changed files with 547 additions and 60 deletions.
diff --git a/doc/Makefile b/doc/Makefile
@@ -43,7 +43,7 @@ check_output: $(EXAMPLES:.cpp=.test)
 
 
 clean:
-	rm -fr me.nlohmann.json.docset html $(EXAMPLES:.cpp=)
+	rm -fr me.nlohmann.json.docset html xml $(EXAMPLES:.cpp=)
 
 
 ##########################################################################

diff --git a/doc/examples/meta.output b/doc/examples/meta.output
@@ -2,9 +2,9 @@
     "compiler": {
         "c++": "201103",
         "family": "clang",
-        "version": "11.0.3 (clang-1103.0.32.62)"
+        "version": "12.0.0 (clang-1200.0.22.19)"
     },
-    "copyright": "(C) 2013-2017 Niels Lohmann",
+    "copyright": "(C) 2013-2020 Niels Lohmann",
     "name": "JSON for Modern C++",
     "platform": "apple",
     "url": "https://github.com/nlohmann/json",

diff --git a/doc/mkdocs/docs/api/basic_json/dump.md b/doc/mkdocs/docs/api/basic_json/dump.md
@@ -0,0 +1,72 @@
+# basic_json::dump
+
+```cpp
+string_t dump(const int indent = -1,
+              const char indent_char = ' ',
+              const bool ensure_ascii = false,
+              const error_handler_t error_handler = error_handler_t::strict) const
+```
+
+Serialization function for JSON values. The function tries to mimic
+Python's `json.dumps()` function, and currently supports its `indent`
+and `ensure_ascii` parameters.
+    
+## Parameters
+
+`indent` (in)
+:   If `indent` is nonnegative, then array elements and object
+    members will be pretty-printed with that indent level. An indent level of
+    `0` will only insert newlines. `-1` (the default) selects the most compact
+    representation.
+
+`indent_char` (in)
+:   The character to use for indentation if `indent` is
+    greater than `0`. The default is ` ` (space).
+
+`ensure_ascii` (in)
+:   If `ensure_ascii` is true, all non-ASCII characters
+    in the output are escaped with `\uXXXX` sequences, and the result consists
+    of ASCII characters only.
+
+`error_handler` (in)
+:   how to react on decoding errors; there are three
+    possible values: `strict` (throws and exception in case a decoding error
+    occurs; default), `replace` (replace invalid UTF-8 sequences with U+FFFD),
+    and `ignore` (ignore invalid UTF-8 sequences during serialization; all
+    bytes are copied to the output unchanged).
+    
+## Return value
+
+string containing the serialization of the JSON value
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no
+changes to any JSON value.
+
+## Complexity
+
+Linear.
+
+## Notes
+
+Binary values are serialized as object containing two keys:
+
+- "bytes": an array of bytes as integers
+- "subtype": the subtype as integer or `#!json null` if the binary has no subtype
+
+## Example
+
+The following example shows the effect of different `indent`,
+    `indent_char`, and `ensure_ascii` parameters to the result of the
+    serialization.
+
+```cpp
+--8<-- "examples/dump.cpp"
+```
+
+Output:
+
+```json
+--8<-- "examples/dump.output"
+```
diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md
@@ -0,0 +1,15 @@
+# Overview
+
+!!! note
+
+    This page is under construction.
+
+## Member functions
+
+### Object inspection
+
+- [dump](dump.md) - serialization
+
+## Static functions
+
+- [meta](meta.md) - returns version information on the library
diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md
@@ -0,0 +1,45 @@
+# basic_json::meta
+
+```cpp
+static basic_json meta();
+```
+
+This function returns a JSON object with information about the library,
+including the version number and information on the platform and compiler.
+
+## Return value
+
+JSON object holding version information
+
+key         | description
+----------- | ---------------
+`compiler`  | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version).
+`copyright` | The copyright line for the library as string.
+`name`      | The name of the library as string.
+`platform`  | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`.
+`url`       | The URL of the project as string.
+`version`   | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string).
+
+## Exception safety
+
+Strong guarantee: if an exception is thrown, there are no
+changes to any JSON value.
+
+## Complexity
+
+Constant.
+
+## Example
+
+The following code shows an example output of the `meta()`
+function.
+
+```cpp
+--8<-- "examples/meta.cpp"
+```
+
+Output:
+
+```json
+--8<-- "examples/meta.output"
+```
diff --git a/doc/mkdocs/docs/features/binary_formats/cbor.md b/doc/mkdocs/docs/features/binary_formats/cbor.md
@@ -64,7 +64,6 @@ binary          | *size*: 4294967296..18446744073709551615   | byte string (8 by
 
 	If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the normal JSON serialization which serializes NaN or Infinity to `null`.
 
-
 !!! info "Unused CBOR types"
 
 	The following CBOR types are not used in the conversion:
@@ -77,13 +76,16 @@ binary          | *size*: 4294967296..18446744073709551615   | byte string (8 by
       - bignum (0xC2..0xC3)
       - decimal fraction (0xC4)
       - bigfloat (0xC5)
-      - tagged items (0xC6..0xD4, 0xD8..0xDB)
       - expected conversions (0xD5..0xD7)
       - simple values (0xE0..0xF3, 0xF8)
       - undefined (0xF7)
       - half-precision floats (0xF9)
       - break (0xFF)
 
+!!! info "Tagged items"
+
+    Binary subtypes will be serialized as tagged items. See [binary values](../binary_values.md#cbor) for an example.
+
 ??? example
 
     ```cpp
@@ -150,7 +152,6 @@ Double-Precision Float | number_float    | 0xFB
      - bignum (0xC2..0xC3)
      - decimal fraction (0xC4)
      - bigfloat (0xC5)
-     - tagged items (0xC6..0xD4, 0xD8..0xDB)
      - expected conversions (0xD5..0xD7)
      - simple values (0xE0..0xF3, 0xF8)
      - undefined (0xF7)
@@ -159,6 +160,10 @@ Double-Precision Float | number_float    | 0xFB
 
 	CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
 
+!!! warning "Tagged items"
+
+    Tagged items will throw a parse error by default. However, they can be ignored by passing `cbor_tag_handler_t::ignore` to function `from_cbor`.
+
 ??? example
 
     ```cpp

diff --git a/doc/mkdocs/docs/features/binary_values.md b/doc/mkdocs/docs/features/binary_values.md
@@ -158,32 +158,33 @@ JSON does not have a binary type, and this library does not introduce a new type
 
 ### CBOR
 
-[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.
+[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Subtypes will be serialized as tags. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.
 
 ??? example
 
     Code:
 
     ```cpp
-    // create a binary value of subtype 42 (will be ignored by CBOR)
+    // create a binary value of subtype 42
     json j;
     j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
 
     // convert to CBOR
     auto v = json::to_cbor(j);      
     ```
             
-    `v` is a `std::vector<std::uint8t>` with the following 13 elements:
+    `v` is a `std::vector<std::uint8t>` with the following 15 elements:
 
     ```c
     0xA1                                   // map(1)
         0x66                               // text(6)
             0x62 0x69 0x6E 0x61 0x72 0x79  // "binary"
+        0xD8 0x2A                          // tag(42)
         0x44                               // bytes(4)
             0xCA 0xFE 0xBA 0xBE            // content
     ```
 
-    Note the subtype (42) is **not** serialized, and deserializing `v` would yield the following value:
+    Note that the subtype is serialized as tag. However, parsing tagged values yield a parse error unless `json::cbor_tag_handler_t::ignore` is passed to `json::from_cbor`.
 
     ```json
     {

diff --git a/doc/mkdocs/docs/features/comments.md b/doc/mkdocs/docs/features/comments.md
@@ -0,0 +1,83 @@
+# Comments
+
+This library does not support comments *by default*. It does so for three reasons:
+
+1. Comments are not part of the [JSON specification](https://tools.ietf.org/html/rfc8259). You may argue that `//` or `/* */` are allowed in JavaScript, but JSON is not JavaScript.
+2. This was not an oversight: Douglas Crockford [wrote on this](https://plus.google.com/118095276221607585885/posts/RK8qyGVaGSr) in May 2012:
+
+	> 	I removed comments from JSON because I saw people were using them to hold parsing directives, a practice which would have destroyed interoperability.  I know that the lack of comments makes some people sad, but it shouldn't. 
+
+	> 	Suppose you are using JSON to keep configuration files, which you would like to annotate. Go ahead and insert all the comments you like. Then pipe it through JSMin before handing it to your JSON parser.
+
+3. It is dangerous for interoperability if some libraries would add comment support while others don't. Please check [The Harmful Consequences of the Robustness Principle](https://tools.ietf.org/html/draft-iab-protocol-maintenance-01) on this.
+
+However, you can pass set parameter `ignore_comments` to `#!c true` in the parse function to ignore `//` or `/* */` comments. Comments will then be treated as whitespace.
+
+!!! example
+
+    Consider the following JSON with comments.
+
+    ```json
+    {
+        // update in 2006: removed Pluto
+        "planets": ["Mercury", "Venus", "Earth", "Mars",
+                    "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
+    }
+    ```
+
+    When calling `parse` without additional argument, a parse error exception is thrown. If `skip_comments` is set to `#! true`, the comments are skipped during parsing:
+
+    ```cpp
+    #include <iostream>
+    #include "json.hpp"
+
+    using json = nlohmann::json;
+
+    int main()
+    {
+        std::string s = R"(
+        {
+            // update in 2006: removed Pluto
+            "planets": ["Mercury", "Venus", "Earth", "Mars",
+                        "Jupiter", "Uranus", "Neptune" /*, "Pluto" */]
+        }
+        )";
+        
+        try
+        {
+            json j = json::parse(s);
+        }
+        catch (json::exception &e)
+        {
+            std::cout << e.what() << std::endl;
+        }
+        
+        json j = json::parse(s,
+                             /* callback */ nullptr,
+                             /* allow exceptions */ true,
+                             /* skip_comments */ true);
+        std::cout << j.dump(2) << '\n';
+    }
+    ```
+
+    Output:
+
+    ```
+    [json.exception.parse_error.101] parse error at line 3, column 9:
+    syntax error while parsing object key - invalid literal;
+    last read: '<U+000A>    {<U+000A>        /'; expected string literal
+    ```
+
+    ```json
+    {
+      "planets": [
+        "Mercury",
+        "Venus",
+        "Earth",
+        "Mars",
+        "Jupiter",
+        "Uranus",
+        "Neptune"
+      ]
+    }
+    ```