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}.