Sync docs for js_json.mli

jscomp/others/js_json.mli

@@ -28,10 +28,10 @@
   **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON)
 *)
 
-(** {2 Types} *)
+(** ## Types *)
 
-(** The JSON data structure *)
 type t
+(** The JSON data structure *)
 
 (** Underlying type of a JSON value *)
 type _ kind =
@@ -51,214 +51,194 @@ type tagged_t =
   | JSONObject of t Js_dict.t
   | JSONArray of t array
 
-
-(** {2 Accessor} *)
+(** ## Accessor *)
 
 val classify : t -> tagged_t
 
-
-val test : 'a  -> 'b kind -> bool
-(** `test v kind` returns true if `v` is of `kind` *)
+val test : 'a -> 'b kind -> bool
+(** `test(v, kind)` returns `true` if `v` is of `kind`. *)
 
 val decodeString : t -> Js_string.t option
-(** `decodeString json` returns `Some s` if `json` is a string, `None`
-    otherwise *)
+(** `decodeString(json)` returns `Some(s)` if `json` is a `string`, `None` otherwise. *)
 
 val decodeNumber : t -> float option
-(** `decodeNumber json` returns `Some n` if `json` is a number, `None`
-    otherwise *)
+(** `decodeNumber(json)` returns `Some(n)` if `json` is a `number`, `None` otherwise. *)
 
 val decodeObject : t -> t Js_dict.t option
-(** `decodeObject json` returns `Some o` if `json` is an object, `None`
-    otherwise *)
+(** `decodeObject(json)` returns `Some(o)` if `json` is an `object`, `None` otherwise. *)
 
 val decodeArray : t -> t array option
-(** `decodeArray json` returns `Some a` if `json` is an array, `None`
-    otherwise *)
+(** `decodeArray(json)` returns `Some(a)` if `json` is an `array`, `None` otherwise. *)
 
 val decodeBoolean : t -> bool option
-(** `decodeBoolean json` returns `Some b` if `json` is a boolean, `None`
-    otherwise *)
+(** `decodeBoolean(json)` returns `Some(b)` if `json` is a `boolean`, `None` otherwise. *)
 
 val decodeNull : t -> 'a Js_null.t option
-(** `decodeNull json` returns `Some null` if `json` is a null, `None`
-    otherwise *)
+(** `decodeNull(json)` returns `Some(null)` if `json` is a `null`, `None` otherwise. *)
 
-(** {2 Construtors} *)
+(** ## Construtors *)
 
-(** Those functions allows the construction of an arbitrary complex
-    JSON values.
+(*
+   Those functions allows the construction of an arbitrary complex
+   JSON values.
 *)
 
-external null : t = "null" [@@bs.val]
-(** `null` is the singleton null JSON value *)
+external null : t = "null"
+  [@@bs.val]
+(** `null` is the singleton null JSON value. *)
 
 external string : string -> t = "%identity"
-(** `string s` makes a JSON string of the `string` `s` *)
+(** `string(s)` makes a JSON string of the `string` `s`. *)
 
 external number : float -> t = "%identity"
-(** `number n` makes a JSON number of the `float` `n` *)
+(** `number(n)` makes a JSON number of the `float` `n`. *)
 
 external boolean : bool -> t = "%identity"
-(** `boolean b` makes a JSON boolean of the `bool` `b` *)
+(** `boolean(b)` makes a JSON boolean of the `bool` `b`. *)
 
 external object_ : t Js_dict.t -> t = "%identity"
-(** `object_ dict` makes a JSON object of the `Js.Dict.t` `dict` *)
-
+(** `object_(dict)` makes a JSON object of the `Js.Dict.t` `dict`. *)
 
 external array : t array -> t = "%identity"
-(** `array_ a` makes a JSON array of the `Js.Json.t array` `a` *)
+(** `array_(a)` makes a JSON array of the `Js.Json.t` array `a`. *)
 
-(**
+(*
   The functions below are specialized for specific array type which
   happened to be already JSON object in the ReScript runtime. Therefore
   they are more efficient (constant time rather than linear conversion).
 *)
 
 external stringArray : string array -> t = "%identity"
-(** `stringArray a` makes a JSON array of the `string array` `a` *)
+(** `stringArray(a)` makes a JSON array of the `string` array `a`. *)
 
 external numberArray : float array -> t = "%identity"
-(** `numberArray a` makes a JSON array of the `float array` `a` *)
+(** `numberArray(a)` makes a JSON array of the `float` array `a`. *)
 
 external booleanArray : bool array -> t = "%identity"
-(** `booleanArray` makes a JSON array of the `bool array` `a` *)
+(** `booleanArray(a)` makes a JSON array of the `bool` array `a`. *)
 
 external objectArray : t Js_dict.t array -> t = "%identity"
-(** `objectArray a` makes a JSON array of the `JsDict.t array` `a` *)
+(** `objectArray(a) makes a JSON array of the `JsDict.t` array `a`. *)
 
-(** {2 String conversion} *)
+(** ## String conversion *)
 
-external parseExn : string -> t = "parse" [@@bs.val] [@@bs.scope "JSON"]
+external parseExn : string -> t = "parse"
+  [@@bs.val] [@@bs.scope "JSON"]
 (**
-  `parseExn s` parses the string `s` into a JSON data structure
-
-  **return** a JSON data structure
-
-  **raise** SyntaxError if given string is not a valid JSON. Note `SyntaxError` is a JavaScript exception.
-
-  ```
-  (* parse a simple JSON string *)
-
-  let json =
-    try
-      Js.Json.parseExn {| "foo" |}
-    with
-    | _ -> failwith "Error parsing JSON string"
-  in
-  match Js.Json.classify json with
-  | Js.Json.JSONString value -> Js.log value
-  | _ -> failwith "Expected a string"
-  ```
-
-  ```
-  (* parse a complex JSON string *)
-
-  let getIds s =
-    let json =
-      try
-        Js.Json.parseExn s
-      with
-      | _ -> failwith "Error parsing JSON string"
-    in
-    match Js.Json.classify json with
-    | Js.Json.JSONObject value ->
-      (* In this branch, compiler infer value : Js.Json.t Js.Dict.t *)
-      begin match Js.Dict.get value "ids" with
-        | Some ids ->
-          begin match Js.Json.classify ids with
-            | Js.Json.JSONArray ids ->
-              (* In this branch compiler infer ids : Js.Json.t array *)
-              ids
-            | _ -> failwith "Expected an array"
-          end
-        | None -> failwith "Expected an `ids` property"
-      end
-    | _ -> failwith "Expected an object"
-
-  (* prints `1, 2, 3` *)
-  let _ =
-    Js.log (getIds {| { "ids" : [1, 2, 3] } |})
-  ```
-
-  **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
+`parseExn(s)` parses the `string` `s` into a JSON data structure.
+Returns a JSON data structure.
+Raises `SyntaxError` if the given string is not a valid JSON. Note: `SyntaxError` is a JavaScript exception.
+
+**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse)
+
+```res example
+/* parse a simple JSON string */
+
+let json = try Js.Json.parseExn(` "hello" `) catch {
+| _ => failwith("Error parsing JSON string")
+}
+
+switch Js.Json.classify(json) {
+| Js.Json.JSONString(value) => Js.log(value)
+| _ => failwith("Expected a string")
+}
+```
+
+```res example
+/* parse a complex JSON string */
+
+let getIds = s => {
+  let json = try Js.Json.parseExn(s) catch {
+  | _ => failwith("Error parsing JSON string")
+  }
+
+  switch Js.Json.classify(json) {
+  | Js.Json.JSONObject(value) =>
+    /* In this branch, compiler infer value : Js.Json.t Js.Dict.t */
+    switch Js.Dict.get(value, "ids") {
+    | Some(ids) =>
+      switch Js.Json.classify(ids) {
+      | Js.Json.JSONArray(ids) => /* In this branch compiler infer ids : Js.Json.t array */
+        ids
+      | _ => failwith("Expected an array")
+      }
+    | None => failwith("Expected an `ids` property")
+    }
+  | _ => failwith("Expected an object")
+  }
+}
+
+/* prints `1, 2, 3` */
+Js.log(getIds(` { "ids" : [1, 2, 3 ] } `))
+```
 *)
 
-external stringify: t -> string = "stringify"
-[@@bs.val] [@@bs.scope "JSON"]
+external stringify : t -> string = "stringify"
+  [@@bs.val] [@@bs.scope "JSON"]
 (**
-  `stringify json` formats the JSON data structure as a string
-
-  **return** the string representation of a given JSON data structure
+`stringify(json)` formats the JSON data structure as a `string`.
+Returns the string representation of a given JSON data structure.
 
-  ```
-  (* Creates and stringifies a simple JS object *)
+**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
 
-  let dict = Js.Dict.empty () in
-  Js.Dict.set dict "name" (Js.Json.string "John Doe");
-  Js.Dict.set dict "age" (Js.Json.number 30.0);
-  Js.Dict.set dict "likes"
-    (Js.Json.stringArray [|"bucklescript";"ocaml";"js"|]);
+```res example
+/* Creates and stringifies a simple JS object */
 
-  Js.log (Js.Json.stringify (Js.Json.object_ dict))
-  ```
+let dict = Js.Dict.empty()
+Js.Dict.set(dict, "name", Js.Json.string("John Doe"))
+Js.Dict.set(dict, "age", Js.Json.number(30.0))
+Js.Dict.set(dict, "likes", Js.Json.stringArray(["bucklescript", "ocaml", "js"]))
 
-  **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
+Js.log(Js.Json.stringify(Js.Json.object_(dict)))
+```
 *)
 
-external stringifyWithSpace: t -> (_ [@bs.as {json|null|json}]) -> int -> string = "stringify"
-[@@bs.val] [@@bs.scope "JSON"]
+external stringifyWithSpace : t -> (_[@bs.as {json|null|json}]) -> int -> string
+  = "stringify"
+  [@@bs.val] [@@bs.scope "JSON"]
 (**
-  `stringify json` formats the JSON data structure as a string
+`stringifyWithSpace(json)` formats the JSON data structure as a `string`.
+Returns the string representation of a given JSON data structure with spacing.
 
-  **return** the string representation of a given JSON data structure
+**See** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
 
-  ```
-  (* Creates and stringifies a simple JS object with spacing *)
+```res example
+/* Creates and stringifies a simple JS object with spacing */
 
-  let dict = Js.Dict.empty () in
-  Js.Dict.set dict "name" (Js.Json.string "John Doe");
-  Js.Dict.set dict "age" (Js.Json.number 30.0);
-  Js.Dict.set dict "likes"
-    (Js.Json.stringArray [|"bucklescript";"ocaml";"js"|]);
+let dict = Js.Dict.empty()
+Js.Dict.set(dict, "name", Js.Json.string("John Doe"))
+Js.Dict.set(dict, "age", Js.Json.number(30.0))
+Js.Dict.set(dict, "likes", Js.Json.stringArray(["bucklescript", "ocaml", "js"]))
 
-  Js.log (Js.Json.stringifyWithSpace (Js.Json.object_ dict) 2)
-  ```
-
-  **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
+Js.log(Js.Json.stringifyWithSpace(Js.Json.object_(dict), 2))
+```
 *)
 
-
 external stringifyAny : 'a -> string option = "stringify"
-[@@bs.val]  [@@bs.scope "JSON"]
+  [@@bs.val] [@@bs.scope "JSON"]
 (**
-  `stringifyAny value` formats any `value` into a JSON string
+`stringifyAny(value)` formats any value into a JSON string.
 
-  ```
-  (* prints ``"foo", "bar"`` *)
-  Js.log (Js.Json.stringifyAny [| "foo"; "bar" |])
-  ```
-
-  **see** [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify)
+```res example
+/* prints `["hello", "world"]` */
+Js.log(Js.Json.stringifyAny(["hello", "world"]))
+```
 *)
 
-
+val deserializeUnsafe : string -> 'a
 (**
   Best-effort serialization, it tries to seralize as
-  many objects as possible and deserialize it back *)
+  many objects as possible and deserialize it back
 
-(**
   It is unsafe in two aspects
   - It may throw during  parsing
   - when you cast it to a specific type, it may have a type mismatch
 *)
-val deserializeUnsafe : string -> 'a
-
 
+val serializeExn : 'a -> string
 (**
   It will raise in such situations:
   - The object can not be serlialized to a JSON
   - There are cycles
   - Some JS engines can not stringify deeply nested json objects
 *)
-val serializeExn : 'a -> string