Misc. documentation improvements

CHANGES.md

@@ -0,0 +1,7 @@
+# Changelog
+
+## Unreleased
+
+## 0.1.0 (2022-10-01)
+
+Initial release.

LICENSE

@@ -1,6 +1,6 @@
 The MIT License
 
-Copyright (c) 2022 Bannerets <comonoid@protonmail.com>
+Copyright (c) 2022-2023 https://github.com/Bannerets <comonoid@proton.me>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -16,8 +16,8 @@ $ opam install kdl
 - [x] Parsing
 - [x] Pretty-printing
 - [x] Lenses
-- [ ] The KDL Query Language
-- [ ] The KDL Schema Language
+- [ ] KDL Query Language (KQL)
+- [ ] KDL Schema Language
 - [ ] Preserve formatting when editing
 <!-- - [ ] ppx_deriving_kdl -->
 
@@ -48,7 +48,7 @@ val kdl : (Kdl.t, Kdl.error) result = Ok
          children = []}]}]}]
 ```
 
-Convert to a sexp-expression:
+Convert to a sexp-expression (uses the `sexplib0` library):
 
 ```ocaml
 # Kdl.sexp_of_t kdl |> Sexplib0.Sexp.to_string_hum |> print_endline
@@ -82,12 +82,12 @@ using `|--` or `//`:
 - : string option = Some "This is the second paragraph"
 ```
 
-Additionaly, type-annotated values can be interpreted:
+Additionaly, type-annotated values can be "interpreted":
 
 ```ocaml
 # let parsed = Kdl.from_string_exn "- (u8)220"
-# Kdl.interpret @@ get_exn parsed (node "-" // arg 0)
-- : Kdl.typed_value = `U8 220
+# Kdl.interpret Kdl.L.(get_exn parsed @@ node "-" // arg 0)
+- : [> Kdl.typed_value ] = `U8 220
 ```
 
 For the full list of available functions, see the [mli][] file.

kdl.opam

@@ -1,11 +1,11 @@
 opam-version: "2.0"
 name: "kdl"
 version: "0.1.0"
-synopsis: "An implementation of the KDL document laguage"
+synopsis: "OCaml implementation of the KDL document laguage"
 maintainer: "github.com/Bannerets <[email protected]>"
 authors: "github.com/Bannerets <[email protected]>"
 license: "MIT"
-tags: ["configuration-language" "serialization-language"]
+tags: ["configuration-language" "data-serialization-language"]
 homepage: "https://github.com/Bannerets/ocaml-kdl"
 bug-reports: "https://github.com/Bannerets/ocaml-kdl/issues"
 dev-repo: "git+https://github.com/Bannerets/ocaml-kdl.git"

kdl.opam.locked

@@ -1,12 +1,11 @@
 opam-version: "2.0"
 name: "kdl"
-version: "0.0.0"
-synopsis: "An implementation of the KDL document laguage"
-description: "An implementation of the KDL document laguage"
-maintainer: "bannerets <[email protected]>"
-authors: "bannerets <[email protected]>"
+version: "0.1.0"
+synopsis: "OCaml implementation of the KDL document laguage"
+maintainer: "github.com/Bannerets <[email protected]>"
+authors: "github.com/Bannerets <[email protected]>"
 license: "MIT"
-tags: ["document-language" "configuration-language" "serialization-language"]
+tags: [ "configuration-language" "data-serialization-language"]
 homepage: "https://github.com/Bannerets/ocaml-kdl"
 bug-reports: "https://github.com/Bannerets/ocaml-kdl/issues"
 depends: [
@@ -20,7 +19,7 @@ depends: [
   "cmdliner" {= "1.1.1" & with-doc}
   "cppo" {= "1.6.9" & with-doc}
   "csexp" {= "1.5.1"}
-  "dune" {= "3.3.1"}
+  "dune" {= "3.9.0"}
   "dune-configurator" {= "3.3.1"}
   "fmt" {= "0.9.0" & with-doc}
   "fpath" {= "0.7.3" & with-doc}
@@ -35,7 +34,7 @@ depends: [
   "ocaml-compiler-libs" {= "v0.12.4"}
   "ocaml-config" {= "2"}
   "ocaml-options-vanilla" {= "1"}
-  "ocamlbuild" {= "0.14.1"}
+  "ocamlbuild" {= "0.14.1" & with-doc}
   "ocamlfind" {= "1.9.5"}
   "odoc" {= "2.1.1" & with-doc}
   "odoc-parser" {= "1.0.1" & with-doc}
@@ -54,28 +53,24 @@ depends: [
   "ppxlib" {= "0.27.0"}
   "re" {= "1.10.4" & with-test}
   "result" {= "1.5" & with-doc}
-  "sedlex" {= "3.0"}
+  "sedlex" {= "3.1"}
   "seq" {= "base"}
   "sexplib0" {= "v0.15.1"}
   "stdio" {= "v0.15.0" & with-test}
   "stdlib-shims" {= "0.3.0"}
   "time_now" {= "v0.15.0" & with-test}
   "topkg" {= "1.0.5" & with-doc}
   "tyxml" {= "4.5.0" & with-doc}
-  "uchar" {= "0.0.2"}
   "uutf" {= "1.0.3" & with-doc}
 ]
 build: [
-  ["dune" "subst"] {dev}
-  [
-    "dune"
-    "build"
-    "-p"
-    name
-    "-j"
-    jobs
-    "@runtest" {with-test}
-    "@doc" {with-doc}
-  ]
+  "dune"
+  "build"
+  "-p"
+  name
+  "-j"
+  jobs
+  "@runtest" {with-test}
+  "@doc" {with-doc}
 ]
 dev-repo: "git+https://github.com/Bannerets/ocaml-kdl.git"

src/kdl.mli

@@ -9,18 +9,15 @@ type value =
   | `Null ]
 (** A KDL value.
 
-    [`String] can be either a regular quoted string (["string"]) or a "raw"
-    string ([r#"raw string"#]).
+    Note: Although the KDL spec does not differentiate integers and floats, a
+    number is parsed as [`Float] if it is written in the [e] scientific notation
+    or contains a [.], same as in OCaml. If an integer is too large for the
+    OCaml [int], the integer is parsed as [`RawInt] instead of [`Int]. *)
 
-    Although the KDL spec does not differentiate integers and floats, a number
-    is parsed as [`Float] if it is written in the [e] scientific notation or
-    contains a [.], same as in OCaml.
-
-    If an integer is too large for the OCaml [int], the integer is parsed as
-    [`RawInt] instead of [`Int]. *)
+(*_ TODO: Change to `Number? *)
 
 type annot_value = string option * value
-(** An annotated value: [opt_annot * value].
+(** A KDL value with an optional type annotation: [opt_annot * value].
     For example, [(Some "u16", `Int 3201)] is an [annot_value]. *)
 
 type prop = string * annot_value
@@ -42,19 +39,24 @@ type t = node list
 (** {1 Parsing} *)
 
 type error_loc = Lexing.position * Lexing.position
-(** Note: the positions count unicode code points, not bytes. *)
+(** The location generated by [sedlex].
+    Note: the positions count unicode code points, not bytes. *)
 
 type error = string * error_loc
+(** A parsing error. *)
 
 val show_error : error -> string
 
 exception Parse_error of error
 
 val from_string : ?fname:string -> string -> (t, error) result
-(** Parse KDL from a string. *)
+(** Parse KDL from a string. The string should be UTF8-encoded. [?fname] is
+    an optional filename that is used in locations. *)
 
 val from_string_exn : ?fname:string -> string -> t
-(** @raise Parse_error instead of returning a [result]. *)
+(** [from_string_exn] is a raising version of [from_string].
+
+    @raise Parse_error *)
 
 val from_channel : ?fname:string -> in_channel -> (t, error) result
 (** Parse KDL from a channel. *)
@@ -76,13 +78,14 @@ val node : ?annot:string
         -> ?props:prop list
         -> node list
         -> node
-(** [node ?annot name ?args ?props children] creates a {!type:node}. *)
+(** [node ?annot name ?args ?props children] constructs a {!type:node}. *)
 
 val arg : ?annot:string -> value -> annot_value
-(** [arg ?annot value] creates an argument. *)
+(** [arg ?annot value] constructs an argument (that is, a value with an optional
+    annotation). *)
 
 val prop : ?annot:string -> string -> value -> prop
-(** [prop ?annot name value] creates a property. *)
+(** [prop ?annot name value] constructs a property. *)
 
 (** {1 Equivalence} *)
 
@@ -111,7 +114,7 @@ val sexp_of_t : t -> Sexplib0.Sexp.t
 (** {1 Pretty-printing} *)
 
 val indent : int ref
-(** [indent] is a number of spaces used per indentation level.
+(** [indent] is the number of spaces used per indentation level.
     By default, [indent] is set to [2]. *)
 
 val pp_value : Format.formatter -> [< value] -> unit
@@ -138,20 +141,20 @@ val pp_compact : Format.formatter -> t -> unit
 (** Same as {!pp}, but outputs the result in one line. *)
 
 val to_string : t -> string
-(** Same as {!pp}, but outputs the result into a string. *)
+(** Pretty-print a KDL document into a string using {!pp}. *)
 
 val show : t -> string
 (** Alias for [to_string]. *)
 
 (** {1 Type annotations} *)
 
 (** KDL {{:https://github.com/kdl-org/kdl/blob/1.0.0/SPEC.md#type-annotation} defines}
-    reserved type annotations, some of them are supported out of the box.
-    An annotated value can be interpreted using the {!interpret} function.
-    If the type annotation is unknown, [`Other] is returned.
+    reserved type annotations. Some of them are supported out of the box in
+    ocaml-kdl. An annotated value can be "interpreted" using the {!interpret}
+    function. If the type annotation is unknown, [`Other] is returned.
 
-    You can extend [typed_value] with custom type annotations e.g. the
-    following way:
+    [typed_value] can be extended with custom type annotations, for example,
+    the following way:
     {[
       type typed_value = [ Kdl.typed_value
                          | `Date of (* ... *) ]
@@ -179,7 +182,9 @@ type typed_value =
   | `Unannotated of value ]
 
 val interpret : annot_value -> [> typed_value]
-(** @raise Failure if a value is invalid. For example, if the value is
+(** Interpret a type-annotated value. [f32] is currently the same as [f64].
+
+    @raise Failure if a value is invalid. For example, if the value is
     annotated as "u8" but exceeds the range of u8, [Failure] is raised. *)
 
 val i8 : annot_value -> int option
@@ -213,8 +218,7 @@ val usize : annot_value -> nativeint option
 (** Interpret a value with the "usize" type annotation as [nativeint]. *)
 
 val f32 : annot_value -> float option
-(** Interpret a value with the "f32" type annotation as [float].
-    This is currently identical to {!f64}. *)
+(** Interpret a value with the "f32" type annotation as [float]. *)
 
 val f64 : annot_value -> float option
 (** Interpret a value with the "f64" type annotation as [float]. *)
@@ -226,8 +230,10 @@ val base64 : annot_value -> bytes option
 (** {1 Lenses} *)
 
 module L : sig
-  (** Note: These lenses are mostly meant for getting, [set] is generally
-      inefficient. *)
+  (** Basic partial lenses for accessing deeply-nested KDL structures.
+
+      Note: These lenses are mostly meant to be used for getting, [set] is
+      generally inefficient. *)
 
   type ('a, 'b) lens =
     { get : 'a -> 'b option
@@ -243,8 +249,11 @@ module L : sig
   (** Alias for [(|--)]. *)
 
   val get : 'a -> ('a, 'b) lens -> 'b option
+  (** Run the getter ([lens.get]). Returns [Some value] if the lens
+      successfully matches, or [None] otherwise.  *)
 
   val set : 'a -> 'b -> ('a, 'b) lens -> 'a option
+  (** Run the setter ([lens.set]). *)
 
   val get_exn : 'a -> ('a, 'b) lens -> 'b
   (** [get_exn a l] is [Option.get (get a l)]. *)
@@ -256,10 +265,11 @@ module L : sig
   (** [(.@())] is an indexing operator for [get]. *)
 
   val (.@()<-) : 'a -> ('a, 'b) lens -> 'b -> 'a option
-  (** [(.@()<-)] is an indexing operator for [set]: it allows you to write
+  (** [(.@()<-)] is an indexing operator for [set]: it allows one to write
       [document.@(lens) <- value] instead of [set document value lens]. *)
 
   val update : ('b -> 'b option) -> 'a -> ('a, 'b) lens -> 'a option
+  (** The combination of [get] and [set]. *)
 
   val node_name : (node, string) lens
   (** Lens to [node.name]. *)
@@ -282,7 +292,7 @@ module L : sig
 
   val arg : int -> (node, annot_value) lens
   (** [arg n] is a lens to the [n]-th argument of a node, starting at 0.
-      This operates in O(n) time. *)
+      Operates in O(n) time. *)
 
   val prop : string -> (node, annot_value) lens
   (** Lens to the property with the specific name. Operates in O(n) time. *)
@@ -361,9 +371,9 @@ module L : sig
   val nth : int -> ('a list, 'a) lens
   (** Lens to the [n]-th element of a list, starting at 0. *)
 
-  val filter : ('a -> bool) -> ('a list, 'a list) lens
-
   val each : ('a, 'b) lens -> ('a list, 'b list) lens
-  (** Make a lens work for multiple items. An example:
+  (** Apply a lens to multiple items. Example:
       [top // child_many "paragraph" // each (arg 0 // value)]. *)
+
+  val filter : ('a -> bool) -> ('a list, 'a list) lens
 end

src/lexer.ml

@@ -3,7 +3,7 @@ open Printf
 
 let error msg = raise @@ Err.CustomLexingError msg
 
-(* [Compl] doesn't seem to work *)
+(* Note: [Compl] doesn't seem to work *)
 let space_chars = [%sedlex.regexp?
     '\t'   (* Character Tabulation U+0009 *)
   | ' '    (* Space U+0020 *)