From 2e9292dd20a294b985b80ed85d468b486ba1df17 Mon Sep 17 00:00:00 2001 From: Paul-Elliot <peada@free.fr> Date: Thu, 27 Jan 2022 11:37:17 +0100 Subject: [PATCH 1/3] improved the entry point of the documentation. Signed-off-by: Paul-Elliot <peada@free.fr> --- doc/dune | 2 ++ doc/index.mld | 27 +++++++++++++++++++++++++++ lib/yojson.cppo.mli | 35 ++++++++++++----------------------- 3 files changed, 41 insertions(+), 23 deletions(-) create mode 100644 doc/dune create mode 100644 doc/index.mld diff --git a/doc/dune b/doc/dune new file mode 100644 index 00000000..f8998de7 --- /dev/null +++ b/doc/dune @@ -0,0 +1,2 @@ +(documentation + (package yojson)) diff --git a/doc/index.mld b/doc/index.mld new file mode 100644 index 00000000..90c19816 --- /dev/null +++ b/doc/index.mld @@ -0,0 +1,27 @@ +{0 The [yojson] library} + +The Yojson library provides runtime functions for reading and writing JSON +data from OCaml. It addresses a few shortcomings of its predecessor +json-wheel and is about twice as fast (2.7x reading, 1.3x writing; results +may vary). +The design goals of Yojson are the following: +- Reducing inter-package dependencies by the use of polymorphic +variants for the JSON tree type. +- Allowing type-aware serializers/deserializers +to read and write directly without going through a generic JSON tree, +for efficiency purposes. +Readers and writers of all JSON syntaxic elements are provided +but are undocumented and meant to be used by generated OCaml code. +- Distinguishing between ints and floats. +- Providing optional extensions of the JSON syntax. +These extensions include comments, arbitrary strings, +optional quotes around field names, tuples and variants. + +See {{:<http://json.org> JSON specification}json specification}. + +Author: Martin Jambon + +{1 Entry point} + +The entry point of this library is the module {!yojson}. + diff --git a/lib/yojson.cppo.mli b/lib/yojson.cppo.mli index a8a006aa..24381fdf 100644 --- a/lib/yojson.cppo.mli +++ b/lib/yojson.cppo.mli @@ -1,30 +1,19 @@ (** - The Yojson library provides runtime functions for reading and writing JSON - data from OCaml. It addresses a few shortcomings of its predecessor - json-wheel and is about twice as fast (2.7x reading, 1.3x writing; results - may vary). - The design goals of Yojson are the following: - - Reducing inter-package dependencies by the use of polymorphic - variants for the JSON tree type. - - Allowing type-aware serializers/deserializers - to read and write directly without going through a generic JSON tree, - for efficiency purposes. - Readers and writers of all JSON syntaxic elements are provided - but are undocumented and meant to be used by generated OCaml code. - - Distinguishing between ints and floats. - - Providing optional extensions of the JSON syntax. - These extensions include comments, arbitrary strings, - optional quotes around field names, tuples and variants. - - @author Martin Jambon - @see <http://json.org> JSON specification - *) + The Yojson library provides several types for representing JSON values, with different use cases. + + - The {{!basic}Basic} JSON type, + - The {{!safe}Safe} JSON type, a superset of JSON with safer support for integers, + - The {{!raw}Raw} JSON type, a superset of JSON, safer but less integrated with ocaml types. + +Each of these different types have their own module. + +*) (** {1 Shared types and functions} *) #include "common.mli" -(** {1 Basic JSON tree type} *) +(** {1:basic Basic JSON tree type} *) module Basic : sig @@ -55,7 +44,7 @@ end #undef STRING end -(** {1 Multipurpose JSON tree type} *) +(** {{1:safe} Multipurpose JSON tree type} *) module Safe : sig @@ -123,7 +112,7 @@ sig #undef VARIANT end -(** {1 Supertype of all JSON tree types} *) +(** {1:raw Supertype of all JSON tree types} *) #define INT #define INTLIT From 029407b6af9c1a308eace208a7fc30a97eb197c5 Mon Sep 17 00:00:00 2001 From: Paul-Elliot <peada@free.fr> Date: Thu, 27 Jan 2022 13:28:14 +0100 Subject: [PATCH 2/3] review comments Signed-off-by: Paul-Elliot <peada@free.fr> --- doc/index.mld | 11 +++-------- lib/yojson.cppo.mli | 2 +- 2 files changed, 4 insertions(+), 9 deletions(-) diff --git a/doc/index.mld b/doc/index.mld index 90c19816..4c9b4c5f 100644 --- a/doc/index.mld +++ b/doc/index.mld @@ -1,23 +1,18 @@ {0 The [yojson] library} The Yojson library provides runtime functions for reading and writing JSON -data from OCaml. It addresses a few shortcomings of its predecessor -json-wheel and is about twice as fast (2.7x reading, 1.3x writing; results -may vary). +data from OCaml. The design goals of Yojson are the following: -- Reducing inter-package dependencies by the use of polymorphic -variants for the JSON tree type. - Allowing type-aware serializers/deserializers to read and write directly without going through a generic JSON tree, for efficiency purposes. -Readers and writers of all JSON syntaxic elements are provided -but are undocumented and meant to be used by generated OCaml code. - Distinguishing between ints and floats. - Providing optional extensions of the JSON syntax. These extensions include comments, arbitrary strings, optional quotes around field names, tuples and variants. +- Eventually supporting the {{:https://json5.org}JSON5} standard -See {{:<http://json.org> JSON specification}json specification}. +See {{:http://json.org}JSON specification}. Author: Martin Jambon diff --git a/lib/yojson.cppo.mli b/lib/yojson.cppo.mli index 24381fdf..79a894c2 100644 --- a/lib/yojson.cppo.mli +++ b/lib/yojson.cppo.mli @@ -3,7 +3,7 @@ - The {{!basic}Basic} JSON type, - The {{!safe}Safe} JSON type, a superset of JSON with safer support for integers, - - The {{!raw}Raw} JSON type, a superset of JSON, safer but less integrated with ocaml types. + - The {{!raw}Raw} JSON type, a superset of JSON, safer but less integrated with OCaml types. Each of these different types have their own module. From a6522aa5dc3cca8deab411d7f54fe6e958b1c7e5 Mon Sep 17 00:00:00 2001 From: Paul-Elliot <peada@free.fr> Date: Mon, 31 Jan 2022 14:58:44 +0100 Subject: [PATCH 3/3] removing json5 mention Signed-off-by: Paul-Elliot <peada@free.fr> --- doc/index.mld | 1 - 1 file changed, 1 deletion(-) diff --git a/doc/index.mld b/doc/index.mld index 4c9b4c5f..cedec8f2 100644 --- a/doc/index.mld +++ b/doc/index.mld @@ -10,7 +10,6 @@ for efficiency purposes. - Providing optional extensions of the JSON syntax. These extensions include comments, arbitrary strings, optional quotes around field names, tuples and variants. -- Eventually supporting the {{:https://json5.org}JSON5} standard See {{:http://json.org}JSON specification}.