From 7fc9bea7293f4a4fed8efb2c9d55be8f8dab6c0b Mon Sep 17 00:00:00 2001
From: John Whitington <john@coherentgraphics.co.uk>
Date: Thu, 27 Jul 2023 12:05:18 +0100
Subject: [PATCH] Documentation for new v2.6 features

---
 cpdfcolours.mli     | 4 +++-
 cpdfcommand.mli     | 2 +-
 cpdfcomposition.mli | 4 ++++
 cpdfextracttext.mli | 5 ++++-
 cpdfjpeg.mli        | 4 +++-
 cpdfpage.mli        | 5 +++--
 cpdfpng.ml          | 2 +-
 cpdfpng.mli         | 9 ++++-----
 cpdfremovetext.mli  | 4 +++-
 cpdfshape.mli       | 1 +
 10 files changed, 27 insertions(+), 13 deletions(-)

diff --git a/cpdfcolours.mli b/cpdfcolours.mli
index 2b7ecea..d9668b9 100644
--- a/cpdfcolours.mli
+++ b/cpdfcolours.mli
@@ -1,2 +1,4 @@
-(* Standard CSS Colours *)
+(** Standard CSS Colours *)
+
+(** Standard CSS Colours, names in lowercase. *)
 val colours : (string * int) list
diff --git a/cpdfcommand.mli b/cpdfcommand.mli
index df9981f..75d8f68 100644
--- a/cpdfcommand.mli
+++ b/cpdfcommand.mli
@@ -1,4 +1,4 @@
-(** PDF Command Line Tools in library form. *)
+(** PDF Command Line Tools in library form *)
 
 (** Call the command line tools with the contents of [Sys.argv] *)
 val go : unit -> unit
diff --git a/cpdfcomposition.mli b/cpdfcomposition.mli
index b380998..c1907ff 100644
--- a/cpdfcomposition.mli
+++ b/cpdfcomposition.mli
@@ -1 +1,5 @@
+(** Show composition of a PDF *)
+
+(** [show_composition filesize json pdf] prints the composition of a document to
+   Standard Output. *)
 val show_composition : int -> bool -> Pdf.t -> unit
diff --git a/cpdfextracttext.mli b/cpdfextracttext.mli
index a143d7c..4c75fca 100644
--- a/cpdfextracttext.mli
+++ b/cpdfextracttext.mli
@@ -1,4 +1,7 @@
-(** Extract text *)
+(** Experimental text extractor *)
+
+(** Extract page text for a given page. *) 
 val extract_page_text : float option -> Pdf.t -> 'a -> Pdfpage.t -> string
 
+(** Extract page text for given page range. *)
 val extract_text : float option -> Pdf.t -> int list -> string 
diff --git a/cpdfjpeg.mli b/cpdfjpeg.mli
index ed45ae4..39393e6 100644
--- a/cpdfjpeg.mli
+++ b/cpdfjpeg.mli
@@ -1,2 +1,4 @@
-(** Return the dimensions of a JPEG *)
+(** JPEG Utilities *)
+
+(** Return the width and height of a JPEG *)
 val jpeg_dimensions : Pdfio.bytes -> int * int
diff --git a/cpdfpage.mli b/cpdfpage.mli
index 7545c5e..e890f0f 100644
--- a/cpdfpage.mli
+++ b/cpdfpage.mli
@@ -1,7 +1,5 @@
 (** Working with pages *)
 
-val change_pattern_matrices_page : Pdf.t -> Pdftransform.transform_matrix -> Pdfpage.t -> Pdfpage.t
-
 (** Print page info (Mediabox etc) to standard output. *)
 val output_page_info : Pdf.t -> int list -> unit
 
@@ -117,3 +115,6 @@ val copy_box : string -> string -> bool -> Pdf.t -> int list -> Pdf.t
 
 (** True if all pages are "upright" i.e no rotation and (0,0)-based. *)
 val allupright : int list -> Pdf.t -> bool
+
+(** When a page is transformed, its patterns must be too. *)
+val change_pattern_matrices_page : Pdf.t -> Pdftransform.transform_matrix -> Pdfpage.t -> Pdfpage.t
diff --git a/cpdfpng.ml b/cpdfpng.ml
index 2e97e9e..a55f56e 100644
--- a/cpdfpng.ml
+++ b/cpdfpng.ml
@@ -1,4 +1,4 @@
-(* Read and write non-interlaced, non-transparent 24 bit PNGs. Such a PNG may
+(* Read non-interlaced, non-transparent 24 bit PNGs. Such a PNG may
    be loaded into a PDF simply by extracting its width and height from the
    IHDR, and concatenating all its IDAT data sections together. *)
 open Pdfutil
diff --git a/cpdfpng.mli b/cpdfpng.mli
index 8686052..6729e46 100644
--- a/cpdfpng.mli
+++ b/cpdfpng.mli
@@ -1,11 +1,10 @@
-(* PNG files, represented only to the extent required to roundtrip PDF image objects *)
+(** Read PNG files *)
+
+(** PNG files, represented only to the extent required to insert as PDF image objects *)
 type t =
   {width : int;
    height : int;
    idat : Pdfio.bytes}
 
-(* Read a non-interlaced, non-transparent 24 bit PNG for inclusion in a PDF file. *)
+(** Read a non-interlaced, non-transparent 24 bit PNG for inclusion in a PDF file. *)
 val read_png : Pdfio.input -> t
-
-(* Write a non-interlaced, non-transparent 24 bit PNG from PDF image contents *)
-val write_png : t -> Pdfio.output -> unit
diff --git a/cpdfremovetext.mli b/cpdfremovetext.mli
index 575e4ae..e250da6 100644
--- a/cpdfremovetext.mli
+++ b/cpdfremovetext.mli
@@ -1,4 +1,6 @@
-(** Remove text added by Cpdfaddtext from the given pages. *)
+(** Remove text from documents *)
+
+(** Remove text added by [Cpdfaddtext] from the given pages. *)
 val removetext : int list -> Pdf.t -> Pdf.t
 
 (** Remove all text from the given pages *)
diff --git a/cpdfshape.mli b/cpdfshape.mli
index d0b8d16..c00b02f 100644
--- a/cpdfshape.mli
+++ b/cpdfshape.mli
@@ -19,6 +19,7 @@ type subpath = hole * closure * segment list
 
 (* A path is made from a number of subpaths. *)
 type path = winding_rule * subpath list
+
 (** The factor by which the radius of a circle is multiplied to find the length
 of the bezier control lines when approximating quarter arcs to make circles. *)
 val kappa : float