Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Improved the entry point of the documentation. #128

Merged
merged 3 commits into from
Jan 31, 2022
Merged

Improved the entry point of the documentation. #128

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
2e9292d
improved the entry point of the documentation.
panglesd Jan 27, 2022
029407b
review comments
panglesd Jan 27, 2022
a6522aa
removing json5 mention
panglesd Jan 31, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions doc/dune
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,2 @@
(documentation
(package yojson))
27 changes: 27 additions & 0 deletions doc/index.mld
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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).
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the mention of json-wheel can be dropped, nobody has used this in many years and it is not maintained.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is that even true? I think we require everything to go through some Safe/Basic/Raw tree type.

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
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"syntactic"? I am not a native speaker though.

but are undocumented and meant to be used by generated OCaml code.
- Distinguishing between ints and floats.
- Providing optional extensions of the JSON syntax.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this should be dropped since we don't aim to provide these going forward and are just keeping them around for now for compatibility.

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

35 changes: 12 additions & 23 deletions lib/yojson.cppo.mli
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- 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.

*)

(** {1 Shared types and functions} *)

#include "common.mli"

(** {1 Basic JSON tree type} *)
(** {1:basic Basic JSON tree type} *)

module Basic :
sig
Expand Down Expand Up @@ -55,7 +44,7 @@ end
#undef STRING
end

(** {1 Multipurpose JSON tree type} *)
(** {{1:safe} Multipurpose JSON tree type} *)

module Safe :
sig
Expand Down Expand Up @@ -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
Expand Down