Started to improve ocamldoc documentation

cpdf.mli

@@ -1,8 +1,36 @@
 (** Coherent PDF Tools Core Routines *)
 open Pdfutil
 
+(** {2 Types and Exceptions} *)
+
 type encoding = Raw | UTF8 | Stripped
 
+exception SoftError of string
+exception HardError of string
+
+(** {2 Debug} *)
+
+(** Debug: Print out a PDF in readable form to the terminal *)
+val print_pdf_objs : Pdf.t -> unit
+
+(** {2 Working with pages} *)
+
+(** Like [Pdfpage.endpage], but from an input and possible password - does the
+minimal work to find the number of pages. *)
+val endpage_io : Pdfio.input -> string option -> string option -> int
+
+(** Given a function from page number and page to page, a document, and a list
+of page numbers to apply it to, apply the function to all those pages. *)
+val process_pages : (int -> Pdfpage.t -> Pdfpage.t) -> Pdf.t -> int list -> Pdf.t
+
+(** Same, but just iterate *)
+val iter_pages : (int -> Pdfpage.t -> unit) -> Pdf.t -> int list -> unit
+
+(** Same, but map *)
+val map_pages : (int -> Pdfpage.t -> 'a) -> Pdf.t -> int list -> 'a list
+
+(** {2 Page specifications and ranges } *)
+
 val parse_pagespec : Pdf.t -> string -> int list
 
 val string_of_pagespec : Pdf.t -> int list -> string
@@ -11,11 +39,7 @@ val validate_pagespec : string -> bool
 
 val name_of_spec : bool -> Pdfmarks.t list -> Pdf.t -> int -> string -> int -> string -> int -> int -> string
 
-(** Debug: Print out a PDF in readable form to the terminal *)
+(** {2 Compress and Decompress} *)
-val print_pdf_objs : Pdf.t -> unit
-
-(** Same, but from an input and possible password - does the minimal work to find the number of pages. *)
-val endpage_io : Pdfio.input -> string option -> string option -> int
 
 (** Compresses all streams in the PDF document which are uncompressed, using
 /FlateDecode, leaving out metadata.  If the PDF is encrypted, does nothing. *)
@@ -23,111 +47,107 @@ val recompress_pdf : Pdf.t -> Pdf.t
 
 val decompress_pdf : Pdf.t -> Pdf.t
 
-(* [set_pdf_info (key, value, version)] sets the entry [key] in the /Info directory, updating
+(** {2 Metadata and settings} *)
+
+(** [copy_id keepversion copyfrom copyto] *) 
+val copy_id : bool -> Pdf.t -> Pdf.t -> Pdf.t
+
+(** [set_pdf_info (key, value, version)] sets the entry [key] in the /Info directory, updating
 the PDF minor version to [version].*)
 val set_pdf_info : (string * Pdf.pdfobject * int) -> Pdf.t -> Pdf.t
 
-(* [set_pdf_info (key, value, version)] sets the entry [key] in the
+(** [set_pdf_info (key, value, version)] sets the entry [key] in the
 /ViewerPreferences directory, updating the PDF minor version to [version].*)
 val set_viewer_preference : (string * Pdf.pdfobject * int) -> Pdf.t -> Pdf.t
 
-(* Set the page layout to the given name (sans slash) e.g SinglePage *)
+(** Set the page layout to the given name (sans slash) e.g SinglePage *)
 val set_page_layout : Pdf.t -> string -> Pdf.t
 
-(* Set the page layout to the given name (sans slash) e.g SinglePage *)
+(** Set the page layout to the given name (sans slash) e.g SinglePage *)
 val set_page_mode : Pdf.t -> string -> Pdf.t
 
-(* Expand the string "now" to a PDF date string, ignoring any other string *)
+val set_version : int -> Pdf.t -> unit
-val expand_date : string -> string
 
-(* Given a function from page number and page to page, a document, and a list
+(** Output to standard output general information about a PDF. *)
-of page numbers to apply it to, apply the function to all those pages. *)
-val process_pages : (int -> Pdfpage.t -> Pdfpage.t) -> Pdf.t -> int list -> Pdf.t
 
-(* Same, but just iterate *)
+val get_info_utf8 : Pdf.t -> string -> string
-val iter_pages : (int -> Pdfpage.t -> unit) -> Pdf.t -> int list -> unit
 
-(* Same, but map *)
+val output_info : encoding -> Pdf.t -> unit
-val map_pages : (int -> Pdfpage.t -> 'a) -> Pdf.t -> int list -> 'a list
 
-(* Two possible error classes. *)
+(** {2 Presentations} *)
-exception SoftError of string
-exception HardError of string
 
-(* [presentation range t d h i dir effect_dur pdf] *)
+(** [presentation range t d h i dir effect_dur pdf] *)
 val presentation : int list -> string option ->
     float option -> bool -> bool -> int -> float -> Pdf.t -> Pdf.t
 
-(* [attach_file keep-version topage pdf filename] *)
+(** {2 File Attachments} *)
+(** [attach_file keep-version topage pdf filename] *)
 val attach_file : bool -> int option -> Pdf.t -> string -> Pdf.t
 
-(* Remove attached files. *)
+(** Remove attached files. *)
 val remove_attached_files : Pdf.t -> Pdf.t
 
-(* List attached files. Attachment name and page number. Page 0 is document level. *)
+(** List attached files. Attachment name and page number. Page 0 is document level. *)
 val list_attached_files : Pdf.t -> (string * int) list
 
-(* [parse_bookmark_file verify pdf input] *)
+(** {2 Bookmarks} *)
+
+(** [parse_bookmark_file verify pdf input] *)
 val parse_bookmark_file : bool -> Pdf.t -> Pdfio.input -> Pdfmarks.t list
 
-(* [add_bookmarks verify input pdf] *) 
+(** [add_bookmarks verify input pdf] *) 
 val add_bookmarks : bool -> Pdfio.input -> Pdf.t -> Pdf.t
 
-(* [copy_id keepversion copyfrom copyto] *) 
+(** [list_bookmarks deunicode range page_offset pdf output] *)
-val copy_id : bool -> Pdf.t -> Pdf.t -> Pdf.t
+val list_bookmarks : encoding -> int list -> Pdf.t -> Pdfio.output -> unit
 
-(* [set_metadata keepversion filename pdf] *) 
+(** {2 XML Metadata} *)
+
+(** [set_metadata keepversion filename pdf] *) 
 val set_metadata : bool -> string -> Pdf.t -> Pdf.t
 
 val set_metadata_from_bytes : bool -> Pdfio.bytes -> Pdf.t -> Pdf.t
 
-(* Remove the metadata from a file *)
+(** Remove the metadata from a file *)
 val remove_metadata : Pdf.t -> Pdf.t
 
-(* [combine_pages fast under over scaletofit swap equalize] *)
+(** Print metadate to stdout *)
-val combine_pages : bool -> Pdf.t -> Pdf.t -> bool -> bool -> bool -> Pdf.t
-
-(* [stamp scale_to_fit fast isover range over pdf] stamps the first page of [over] over each page of the PDF. *)
-val stamp : bool -> bool -> bool -> int list -> Pdf.t -> Pdf.t -> Pdf.t
-
-(* [list_bookmarks deunicode range page_offset pdf output] *)
-val list_bookmarks : encoding -> int list -> Pdf.t -> Pdfio.output -> unit
-
-(* Custom CSP1 *)
-val custom_csp1 : Pdf.t -> Pdf.t
-
-(* Custom CSP2 *)
-val custom_csp2 : float -> Pdf.t -> Pdf.t
-
-(* FIXME: Horrid - should return PDFs, write to file separtely. *)
-(* [split_at_bookmarks linearize nobble level spec pdf] *)
-val split_at_bookmarks : string -> bool -> (Pdf.t -> Pdf.t) -> int -> string -> Pdf.t -> unit
-
-(* The new one *)
-val split_on_bookmarks : Pdf.t -> int -> Pdf.t list
-
-(* [split_pdf printf chunksize linearize nobble spec pdf] *)
-val split_pdf : Pdfwrite.encryption option -> bool -> string -> int -> bool -> (Pdf.t -> Pdf.t) -> string -> Pdf.t -> unit
-
-(* Nobble a page, given pdf, pagenumber and page *)
-val nobble_page : Pdf.t -> 'a -> Pdfpage.t -> Pdfpage.t
-
-(* Print page info (Mediabox etc) *)
-val output_page_info : Pdf.t -> unit
-
-val hasbox : Pdf.t -> int -> string -> bool
-
-(* Print metadate to stdout *)
 val get_metadata : Pdf.t -> Pdfio.bytes
 
 val print_metadata : Pdf.t -> unit
 
-(* Print font list to stdout *)
+(** {2 Stamping} *)
+
+(** [combine_pages fast under over scaletofit swap equalize] *)
+val combine_pages : bool -> Pdf.t -> Pdf.t -> bool -> bool -> bool -> Pdf.t
+
+(** [stamp scale_to_fit fast isover range over pdf] stamps the first page of [over] over each page of the PDF. *)
+val stamp : bool -> bool -> bool -> int list -> Pdf.t -> Pdf.t -> Pdf.t
+
+(** {2 Splitting PDFs} *)
+
+(** [split_at_bookmarks linearize nobble level spec pdf] *)
+val split_at_bookmarks : string -> bool -> (Pdf.t -> Pdf.t) -> int -> string -> Pdf.t -> unit
+
+(** The new one *)
+val split_on_bookmarks : Pdf.t -> int -> Pdf.t list
+
+(** [split_pdf printf chunksize linearize nobble spec pdf] *)
+val split_pdf : Pdfwrite.encryption option -> bool -> string -> int -> bool -> (Pdf.t -> Pdf.t) -> string -> Pdf.t -> unit
+
+(** {2 Listing fonts} *)
+
+(** Print font list to stdout *)
 val print_fonts : Pdf.t -> unit
 
 val list_fonts : Pdf.t -> (int * string * string * string * string) list
 
-(* Possible positions for adding text and other uses. *)
+(** {2 Adding text} *)
+
+(** Expand the string "now" to a PDF date string, ignoring any other string *)
+val expand_date : string -> string
+
+(** Possible positions for adding text and other uses. *)
 type position =
   | PosCentre of float * float
   | PosLeft of float * float
@@ -155,14 +175,14 @@ type justification =
   | CentreJustify
   | RightJustify
 
-(* [calculate ignore_d w (xmin, ymin, xmax, ymax) shorterside pos] *)
+(** [calculate ignore_d w (xmin, ymin, xmax, ymax) shorterside pos] *)
 val calculate_position :
     bool ->
     float ->
     float * float * float * float ->
     orientation -> position -> float * float * float
 
-(* Returns what the added text string would be *)
+(** Returns what the added text string would be *)
 (*val addtext_returntext : Pdf.t -> string -> int -> string -> int -> string*)
 
 val metrics_howmany : unit -> int
@@ -172,7 +192,7 @@ val metrics_y : int -> float
 val metrics_rot : int -> float
 val metrics_baseline_adjustment : unit -> float
 
-(* [add_texts fontname font bates colour positino linespacing fontsize shorterside text pages pdf] *)
+(** [add_texts fontname font bates colour positino linespacing fontsize shorterside text pages pdf] *)
 val addtexts :
     bool -> (*metrics*)
     float -> (*linewidth*)
@@ -197,109 +217,125 @@ val addtexts :
     Pdf.t ->(*pdf*)
     Pdf.t
 
-(* Remove text from the given pages. *)
+(** Remove text from the given pages. *)
 val removetext : int list -> Pdf.t -> Pdf.t
 
-(* Modify the rotation of the page and its contents to leave the rotation at 0 with the page effectively unaltered. *)
+(**  {2 Page geometry} *)
-val upright : ?fast:bool -> int list -> Pdf.t -> Pdf.t
 
-(* [crop_pdf x y w h pdf range] *)
+(** Print page info (Mediabox etc) *)
+val output_page_info : Pdf.t -> unit
+
+val hasbox : Pdf.t -> int -> string -> bool
+
+(** [crop_pdf x y w h pdf range] *)
 val crop_pdf : float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t
 
-(* [set_mediabox x y w h pdf range] *)
+(** [set_mediabox x y w h pdf range] *)
 val set_mediabox : float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t
 
 val setBox : string -> float -> float -> float -> float -> Pdf.t -> int list -> Pdf.t
 
-(* Remove any cropping from the given pages. *)
+(** Remove any cropping from the given pages. *)
 val remove_cropping_pdf : Pdf.t -> int list -> Pdf.t
 val remove_trim_pdf : Pdf.t -> int list -> Pdf.t
 val remove_bleed_pdf : Pdf.t -> int list -> Pdf.t
 val remove_art_pdf : Pdf.t -> int list -> Pdf.t
 
-(* Change rotation to a given value 0, 90, 180, 270 on given pages. *)
+(** Change rotation to a given value 0, 90, 180, 270 on given pages. *)
 val rotate_pdf : int -> Pdf.t -> int list -> Pdf.t
 
-(* Rotate clockwise by 0, 90, 180, 270 on given pages. *)
+(** Rotate clockwise by 0, 90, 180, 270 on given pages. *)
 val rotate_pdf_by : int -> Pdf.t -> int list -> Pdf.t
 
-(* Rotate the contents by the given angle on the given pages. *)
+(** Rotate the contents by the given angle on the given pages. *)
 val rotate_contents : ?fast:bool -> float -> Pdf.t -> int list -> Pdf.t
 
-(* Flip the given pages vertically *)
+(** Modify the rotation of the page and its contents to leave the rotation at 0 with the page effectively unaltered. *)
+val upright : ?fast:bool -> int list -> Pdf.t -> Pdf.t
+
+(** Flip the given pages vertically *)
 val vflip_pdf : ?fast:bool -> Pdf.t -> int list -> Pdf.t
 
-(* Flip the given pages horizontally *)
+(** Flip the given pages horizontally *)
 val hflip_pdf : ?fast:bool -> Pdf.t -> int list -> Pdf.t
 
-(* Shift a PDF in x and y (in pts) in the given pages. *)
+(** Shift a PDF in x and y (in pts) in the given pages. *)
 val shift_pdf : ?fast:bool -> float -> float -> Pdf.t -> int list -> Pdf.t
 
-(* Scale a PDF in sx, sy in the given pages. *)
+(** Scale a PDF in sx, sy in the given pages. *)
 val scale_pdf : ?fast:bool -> float -> float -> Pdf.t -> int list -> Pdf.t
 
-(* FIXME: See .ml *)
+(** [scale_to_fit_pdf input_scale x y op pdf range] *) 
-(* [scale_to_fit_pdf input_scale x y op pdf range] *) 
 val scale_to_fit_pdf : ?fast:bool -> float -> float -> float -> 'a -> Pdf.t -> int list -> Pdf.t
 
-(* Scale the contents of a page by a given factor centred around a given point in a given range. *)
+(** Scale the contents of a page by a given factor centred around a given point in a given range. *)
 val scale_contents : ?fast:bool -> position -> float -> Pdf.t -> int list -> Pdf.t
 
-(* Put blank pages before the given page numbers *)
+(** {2 Padding} *)
+
+(** Put blank pages before the given page numbers *)
 val padbefore : int list -> Pdf.t -> Pdf.t
 
-(* Put blank pages after the given page numbers *)
+(** Put blank pages after the given page numbers *)
 val padafter : int list -> Pdf.t -> Pdf.t
 
-(* Pad to a multiple of n pages *)
+(** Pad to a multiple of n pages *)
 val padmultiple : int -> Pdf.t -> Pdf.t
 
-(* List the annotations to standard output *)
+(** {2 Annotations} *)
+
+(** List the annotations to standard output *)
 val list_annotations : encoding -> Pdf.t -> unit
 
 val list_annotations_more : Pdf.t -> unit
 
 val get_annotations : encoding -> Pdf.t -> (int * string) list
 
-(* Copy the annotations on a given set of pages from a to b yielding c. *)
+(** Copy the annotations on a given set of pages from a to b yielding c. *)
 val copy_annotations : int list -> Pdf.t -> Pdf.t -> Pdf.t
 
-(* Remove the annotations on given pages. *)
+(** Remove the annotations on given pages. *)
 val remove_annotations : int list -> Pdf.t -> Pdf.t
 
-(* Two-up a PDF. *)
+(** {2 Imposition} *)
+
+(** Two-up a PDF. *)
 val twoup : Pdf.t -> Pdf.t
 
-(* Stack Two-up a PDF. *)
+(** Stack Two-up a PDF. *)
 val twoup_stack : Pdf.t -> Pdf.t
 
-(* Output to standard output general information about a PDF. *)
+(** {2 Making new documents} *)
-(*val get_info : bool -> Pdf.t -> string -> string*)
-
-val get_info_utf8 : Pdf.t -> string -> string
-
-val output_info : encoding -> Pdf.t -> unit
-
-(* Make all lines in the PDF at least a certain thickness. *)
-val thinlines : int list -> float -> Pdf.t -> Pdf.t
-
-(* Make all text on certain pages black. *)
-val blacktext : int list -> Pdf.t -> Pdf.t
-
-(* Make all lines on certain pages black. *)
-val blacklines : int list -> Pdf.t -> Pdf.t
-
-(* Make all fills on certain pages black. *)
-val blackfills : int list -> Pdf.t -> Pdf.t
-
-(* Remove images from a PDF, optionally adding crossed boxes. *)
-val draft : bool -> int list -> Pdf.t -> Pdf.t
-
-val set_version : int -> Pdf.t -> unit
-
-(*i val pdf_of_pages : Pdfmarks.bookmark list option -> int list -> Pdfdoc.page list -> Pdf.t -> Pdf.t i*)
 
 val blank_document : float -> float -> int -> Pdf.t
 
 val blank_document_paper : Pdfpaper.t -> int -> Pdf.t
 
+(** {2 Miscellany} *)
+
+(** Make all lines in the PDF at least a certain thickness. *)
+val thinlines : int list -> float -> Pdf.t -> Pdf.t
+
+(** Make all text on certain pages black. *)
+val blacktext : int list -> Pdf.t -> Pdf.t
+
+(** Make all lines on certain pages black. *)
+val blacklines : int list -> Pdf.t -> Pdf.t
+
+(** Make all fills on certain pages black. *)
+val blackfills : int list -> Pdf.t -> Pdf.t
+
+(** Remove images from a PDF, optionally adding crossed boxes. *)
+val draft : bool -> int list -> Pdf.t -> Pdf.t
+
+(**/**)
+
+(** Custom CSP1 *)
+val custom_csp1 : Pdf.t -> Pdf.t
+
+(** Custom CSP2 *)
+val custom_csp2 : float -> Pdf.t -> Pdf.t
+
+(** Nobble a page, given pdf, pagenumber and page *)
+val nobble_page : Pdf.t -> 'a -> Pdfpage.t -> Pdfpage.t
+

cpdfcommand.mli

@@ -1,7 +1,11 @@
-(* cpdfcommand.mli *)
+(** PDF Command Line Tools in library form. *)
+
+(** Call the command line tools with the contents of [Sys.argv] *)
 val go : unit -> unit
 
+(** Call the command line tools with a specialised [argv] of our own *)
 val go_withargv : string array -> unit
 
+(**/**)
 val demo : bool
 

cpdfstrftime.mli

@@ -1,2 +1,4 @@
-(* C-style strftime *)
+(** C-style strftime *)
+
+(** This supports the following format specifiers: %a %A %b %B %s %e %H %I %j %m %M %p %S %T %u %w %Y %% *)
 val strftime : string -> string