Improve doc.

savonet · Dec 14, 2023 · 308e5cb · 308e5cb
1 parent 1f03348
commit 308e5cb
Show file tree

Hide file tree

Showing 4 changed files with 38 additions and 130 deletions.
diff --git a/CHANGES.md b/CHANGES.md
@@ -1,8 +1,7 @@
 0.3.0 (unreleased)
 =====
 - Add basic example.
-- Add optional custom parser argument to override the
-  default parsing mechanism.
+- Add optional custom parser argument to override the default parsing mechanism.
 
 0.2.0 (2023-07-01)
 =====

diff --git a/examples/meta.ml b/examples/meta.ml
@@ -14,8 +14,7 @@ let () =
     match !format with
       | "id3" | "mp3" -> Metadata.ID3.parse_file
       | "id3v1" -> Metadata.ID3v1.parse_file
-      | "id3v2" ->
-          fun ?custom_parser f -> Metadata.ID3v2.parse_file ?custom_parser f
+      | "id3v2" -> fun ?custom_parser f -> Metadata.ID3v2.parse_file ?custom_parser f
       | "ogg" -> Metadata.OGG.parse_file
       | "mp4" -> Metadata.MP4.parse_file
       | "" -> Metadata.Any.parse_file

diff --git a/src/metadata.mli b/src/metadata.mli
@@ -43,11 +43,9 @@ module Make : functor (_ : CharEncoding.T) -> sig
     (** Go back at the beginning of the stream. *)
     val reset : t -> unit
 
-    val with_file :
-      ?custom_parser:custom_parser -> (t -> metadata) -> string -> metadata
+    val with_file : ?custom_parser:custom_parser -> (t -> metadata) -> string -> metadata
 
-    val with_string :
-      ?custom_parser:custom_parser -> (t -> metadata) -> string -> metadata
+    val with_string : ?custom_parser:custom_parser -> (t -> metadata) -> string -> metadata
   end
 
   module ID3v1 = MetadataID3v1
@@ -68,46 +66,44 @@ module Make : functor (_ : CharEncoding.T) -> sig
   module ID3 : sig
     val parse : Reader.t -> (string * string) list
 
-    val parse_file :
-      ?custom_parser:custom_parser -> string -> (string * string) list
+    val parse_file : ?custom_parser:custom_parser -> string -> (string * string) list
   end
 
   (** Return the first application which does not raise invalid. *)
   val first_valid : (Reader.t -> metadata) list -> Reader.t -> metadata
 
   module Audio : sig
     val parsers : (Reader.t -> MetadataBase.metadata) list
+
     val parse : Reader.t -> MetadataBase.metadata
 
-    val parse_file :
-      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+    val parse_file : ?custom_parser:custom_parser -> string -> MetadataBase.metadata
   end
 
   module Image : sig
     val parsers : (Reader.t -> MetadataBase.metadata) list
+
     val parse : Reader.t -> MetadataBase.metadata
 
-    val parse_file :
-      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+    val parse_file : ?custom_parser:custom_parser -> string -> MetadataBase.metadata
   end
 
   module Video : sig
     val parsers : (Reader.t -> MetadataBase.metadata) list
+
     val parse : Reader.t -> MetadataBase.metadata
 
-    val parse_file :
-      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+    val parse_file : ?custom_parser:custom_parser -> string -> MetadataBase.metadata
   end
 
   module Any : sig
     val parsers : (Reader.t -> MetadataBase.metadata) list
+
     val parse : Reader.t -> MetadataBase.metadata
 
-    val parse_file :
-      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+    val parse_file : ?custom_parser:custom_parser -> string -> MetadataBase.metadata
 
-    val parse_string :
-      ?custom_parser:custom_parser -> string -> MetadataBase.metadata
+    val parse_string : ?custom_parser:custom_parser -> string -> MetadataBase.metadata
   end
 
   include module type of Any

diff --git a/src/metadataID3v2.mli b/src/metadataID3v2.mli
@@ -1,20 +1,17 @@
-module R = MetadataBase.Reader
-
-val read_size : synch_safe:bool -> R.t -> int
-val read_size_v2 : R.t -> int
-val unterminate : int -> string -> string
-val next_substring : int -> ?offset:int -> string -> int
-val normalize_id : string -> string
-val make_recode : MetadataCharEncoding.recode option -> int -> string -> string
-val parse : ?recode:MetadataCharEncoding.recode -> R.t -> MetadataBase.metadata
+(** Parse the ID3v2 header. *)
+val parse : ?recode:MetadataCharEncoding.recode -> MetadataBase.Reader.t -> MetadataBase.metadata
 
+(** Parse the ID3v2 header from a file. *)
 val parse_file :
   ?recode:MetadataCharEncoding.recode ->
   ?custom_parser:MetadataBase.custom_parser ->
   string ->
   MetadataBase.metadata
 
-val dump : R.t -> string
+(** Dump the ID3v2 header. *)
+val dump : MetadataBase.Reader.t -> string
+
+(** Dump the ID3v2 header from a file. *)
 val dump_file : string -> string
 
 type apic = {
@@ -31,9 +28,13 @@ type pic = {
   pic_data : string;
 }
 
+(** Parse an APIC tag (containing album art). *)
 val parse_apic : ?recode:MetadataCharEncoding.recode -> string -> apic
+
+(** Parse a PIC tag (containing album art). *)
 val parse_pic : ?recode:MetadataCharEncoding.recode -> string -> pic
 
+(** Frame identifier. *)
 type frame_id =
   [ `AENC
   | `APIC
@@ -110,109 +111,22 @@ type frame_id =
   | `WPUB
   | `WXXX ]
 
-val string_of_frame_id :
-  [< `AENC
-  | `APIC
-  | `COMM
-  | `COMR
-  | `ENCR
-  | `EQUA
-  | `ETCO
-  | `GEOB
-  | `GRID
-  | `IPLS
-  | `LINK
-  | `MCDI
-  | `MLLT
-  | `OWNE
-  | `PCNT
-  | `POPM
-  | `POSS
-  | `PRIV
-  | `RBUF
-  | `RVAD
-  | `RVRB
-  | `SYLT
-  | `SYTC
-  | `TALB
-  | `TBPM
-  | `TCOM
-  | `TCON
-  | `TCOP
-  | `TDAT
-  | `TDLY
-  | `TENC
-  | `TEXT
-  | `TFLT
-  | `TIME
-  | `TIT1
-  | `TIT2
-  | `TIT3
-  | `TKEY
-  | `TLAN
-  | `TLEN
-  | `TMED
-  | `TOAL
-  | `TOFN
-  | `TOLY
-  | `TOPE
-  | `TORY
-  | `TOWN
-  | `TPE1
-  | `TPE2
-  | `TPE3
-  | `TPE4
-  | `TPOS
-  | `TPUB
-  | `TRCK
-  | `TRDA
-  | `TRSN
-  | `TRSO
-  | `TSIZ
-  | `TSRC
-  | `TSSE
-  | `TXXX
-  | `TYER
-  | `UFID
-  | `USER
-  | `USLT
-  | `WCOM
-  | `WCOP
-  | `WOAF
-  | `WOAR
-  | `WOAS
-  | `WORS
-  | `WPAY
-  | `WPUB
-  | `WXXX ] ->
-  string
-
-type frame_flag =
-  [ `File_alter_preservation of bool | `Tag_alter_perservation of bool ]
-
-val default_flags :
-  [> `AENC
-  | `EQUA
-  | `ETCO
-  | `MLLT
-  | `POSS
-  | `RVAD
-  | `SYLT
-  | `SYTC
-  | `TENC
-  | `TLEN
-  | `TSIZ ] ->
-  [> `File_alter_preservation of bool | `Tag_alter_perservation of bool ] list
+(** String representation of a frame identifier. *)
+val string_of_frame_id : frame_id -> string
 
+(** Charset for encoding text. *)
 type text_encoding = [ `ISO_8859_1 | `UTF_16 | `UTF_16BE | `UTF_16LE | `UTF_8 ]
+
+(** Data contained in a frame. *)
 type frame_data = [ `Text of text_encoding * string ]
+
+type frame_flag = [ `File_alter_preservation of bool | `Tag_alter_perservation of bool ]
+
+(** Default flags for a frame. *)
+val default_flags : frame_id -> frame_flag list
+
+(** A ID3 frame. *)
 type frame = { id : frame_id; data : frame_data; flags : frame_flag list }
 
-val write_string : buf:Buffer.t -> string -> unit
-val write_int32 : buf:Buffer.t -> int -> unit
-val write_int16 : buf:Buffer.t -> int -> unit
-val write_int : buf:Buffer.t -> int -> unit
-val write_size : buf:Buffer.t -> int -> unit
-val render_frame_data : version:int -> frame_data -> string
-val render_frames : version:int -> frame list -> Buffer.t
+(** Create an ID3v2 header. *)
 val make : version:int -> frame list -> string