Document Json_error

lib/common.mli

@@ -1,8 +1,10 @@
 val version : string
 
 exception Json_error of string
+(** Exception (usually) describing a parsing failure. *)
 
 val json_error : string -> 'a
+(** @raise Json_error *)
 
 type lexer_state = {
   buf : Buffer.t;

lib/read.mli

@@ -1,10 +1,10 @@
 val prettify : ?std:bool -> string -> string
   (** Combined parser and pretty-printer.
-      See [to_string] for the role of the optional [std] argument. *)
+      See [to_string] for the role of the optional [std] argument and raised exceptions. *)
 
 val compact : ?std:bool -> string -> string
   (** Combined parser and printer.
-      See [to_string] for the role of the optional [std] argument. *)
+      See [to_string] for the role of the optional [std] argument and raised exceptions. *)
 
 (** {2 JSON readers} *)
 
@@ -22,6 +22,7 @@ val from_string :
       @param fname data file name to be used in error messages. It does
       not have to be a real file.
       @param lnum number of the first line of input. Default is 1.
+      @raise Json_error if parsing fails.
   *)
 
 val from_channel :
@@ -30,15 +31,15 @@ val from_channel :
   ?lnum:int ->
   in_channel -> t
   (** Read a JSON value from a channel.
-      See [from_string] for the meaning of the optional arguments. *)
+      See [from_string] for the meaning of the optional arguments and raised exceptions. *)
 
 val from_file :
   ?buf:Buffer.t ->
   ?fname:string ->
   ?lnum:int ->
   string -> t
   (** Read a JSON value from a file.
-      See [from_string] for the meaning of the optional arguments. *)
+      See [from_string] for the meaning of the optional arguments and raised exceptions. *)
 
 
 type lexer_state = Lexer_state.t = {
@@ -65,7 +66,7 @@ val from_lexbuf :
   Lexing.lexbuf -> t
   (** Read a JSON value from a lexbuf.
       A valid initial [lexer_state] can be created with [init_lexer].
-      See [from_string] for the meaning of the optional arguments.
+      See [from_string] for the meaning of the optional arguments and raised exceptions.
 
       @param stream indicates whether more data may follow. The default value
       is false and indicates that only JSON whitespace can be found between
@@ -78,7 +79,7 @@ val seq_from_string :
   string -> t Seq.t
   (** Input a sequence of JSON values from a string.
       Whitespace between JSON values is fine but not required.
-      See [from_string] for the meaning of the optional arguments. *)
+      See [from_string] for the meaning of the optional arguments and raised exceptions. *)
 
 val seq_from_channel :
   ?buf:Buffer.t ->
@@ -94,7 +95,7 @@ val seq_from_channel :
       @raise Finally When the parsing and the finalizer both raised, [Finally (exn, fin_exn)]
       is raised, [exn] being the parsing exception and [fin_exn] the finalizer one.
 
-      See [from_string] for the meaning of the other optional arguments. *)
+      See [from_string] for the meaning of the other optional arguments and other raised exceptions. *)
 
 val seq_from_file :
   ?buf:Buffer.t ->
@@ -104,7 +105,7 @@ val seq_from_file :
   (** Input a sequence of JSON values from a file.
       Whitespace between JSON values is fine but not required.
 
-      See [from_string] for the meaning of the optional arguments. *)
+      See [from_string] for the meaning of the optional arguments and raised exceptions. *)
 
 val seq_from_lexbuf :
   lexer_state ->
@@ -117,7 +118,7 @@ val seq_from_lexbuf :
       is raised, [exn] being the parsing exception and [fin_exn] the finalizer one.
 
       See [seq_from_channel] for the meaning of the optional [fin]
-      argument. *)
+      argument and other raised exceptions. *)
 
 
 type json_line = [ `Json of t | `Exn of exn ]
@@ -135,7 +136,7 @@ val lineseq_from_channel :
 
       See [seq_from_channel] for the meaning of the optional [fin]
       argument.
-      See [from_string] for the meaning of the other optional arguments. *)
+      See [from_string] for the meaning of the other optional arguments and returned exceptions. *)
 
 val lineseq_from_file :
   ?buf:Buffer.t ->
@@ -148,7 +149,7 @@ val lineseq_from_file :
 
       See [seq_from_channel] for the meaning of the optional [fin]
       argument.
-      See [from_string] for the meaning of the other optional arguments. *)
+      See [from_string] for the meaning of the other optional arguments and returned exceptions. *)
 
 val read_t : lexer_state -> Lexing.lexbuf -> t
 (** Read a JSON value from the given lexer_state and lexing buffer and return it.

lib/write.mli

@@ -18,6 +18,7 @@ val to_string :
       refuse to print NaN and infinities,
       require the root node to be either an object or an array.
       Default is [false].
+      @raise Json_error if [float] value is not allowed in standard JSON.
   *)
 
 val to_channel :
@@ -29,7 +30,7 @@ val to_channel :
   (** Write a compact JSON value to a channel.
       Note: the [out_channel] is not flushed by this function.
 
-      See [to_string] for the role of the optional arguments. *)
+      See [to_string] for the role of the optional arguments and raised exceptions. *)
 
 val to_output :
   ?buf:Buffer.t ->
@@ -39,15 +40,15 @@ val to_output :
   < output : string -> int -> int -> int; .. > -> t -> unit
   (** Write a compact JSON value to an OO channel.
 
-      See [to_string] for the role of the optional arguments. *)
+      See [to_string] for the role of the optional arguments and raised exceptions. *)
 
 val to_file :
   ?len:int ->
   ?std:bool ->
   ?suf:string ->
   string -> t -> unit
   (** Write a compact JSON value to a file.
-      See [to_string] for the role of the optional arguments.
+      See [to_string] for the role of the optional arguments and raised exceptions.
       @param suf is a suffix appended to the output Newline by default
       for POSIX compliance. *)
 
@@ -56,7 +57,7 @@ val to_buffer :
   ?std:bool ->
   Buffer.t -> t -> unit
   (** Write a compact JSON value to an existing buffer.
-      See [to_string] for the role of the optional argument. *)
+      See [to_string] for the role of the optional argument and raised exceptions. *)
 
 val seq_to_string :
   ?buf:Buffer.t ->
@@ -67,7 +68,7 @@ val seq_to_string :
   (** Write a sequence of [suf]-suffixed compact one-line JSON values to
       a string.
       @param suf is the suffix ouf each value written. Newline by default.
-      See [to_string] for the role of the optional arguments. *)
+      See [to_string] for the role of the optional arguments and raised exceptions. *)
 
 val seq_to_channel :
   ?buf:Buffer.t ->
@@ -78,7 +79,7 @@ val seq_to_channel :
   (** Write a sequence of [suf]-suffixed compact one-line JSON values to
       a channel.
       @param suf is the suffix of each value written. Newline by default.
-      See [to_channel] for the role of the optional arguments. *)
+      See [to_channel] for the role of the optional arguments and raised exceptions. *)
 
 val seq_to_file :
   ?len:int ->
@@ -88,7 +89,7 @@ val seq_to_file :
   (** Write a sequence of [suf]-suffixed compact one-line JSON values to
       a file.
       @param suf is the suffix of each value written. Newline by default.
-      See [to_string] for the role of the optional arguments. *)
+      See [to_string] for the role of the optional arguments and raised exceptions. *)
 
 val seq_to_buffer :
   ?suf:string ->
@@ -98,7 +99,7 @@ val seq_to_buffer :
   (** Write a sequence of [suf]-suffixed compact one-line JSON values to
       an existing buffer.
       @param suf is the suffix of each value written. Newline by default.
-      See [to_string] for the role of the optional arguments. *)
+      See [to_string] for the role of the optional arguments and raised exceptions. *)
 
 val write_t : Buffer.t -> t -> unit
 (** Write the given JSON value to the given buffer.

lib/write2.mli

@@ -3,15 +3,18 @@
 val pretty_print : ?std:bool -> Format.formatter -> t -> unit
   (** Pretty-print into a {!Format.formatter}.
       See [to_string] for the role of the optional [std] argument.
+      @raise Json_error if [float] value is not allowed in standard JSON.
 
       @since 1.3.1 *)
 
 val pretty_to_string : ?std:bool -> t -> string
   (** Pretty-print into a string.
       See [to_string] for the role of the optional [std] argument.
+      See [pretty_print] for raised exceptions.
   *)
 
 val pretty_to_channel : ?std:bool -> out_channel -> t -> unit
   (** Pretty-print to a channel.
       See [to_string] for the role of the optional [std] argument.
+      See [pretty_print] for raised exceptions.
   *)