Libguestfs - Sep 2015 - [PATCH 2/2] ocaml: Improve ocamldoc.

Using 'ocamlfind ocamldoc' is much faster than running
'ocamldoc'
directly, because ocamlfind will run the native code program
'ocamldoc.opt' if it is available.

This change approximately halves the time taken to compile the ocaml
bindings.
---
 ocaml/Makefile.am | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/ocaml/Makefile.am b/ocaml/Makefile.am
index a535b43..b9828e1 100644
--- a/ocaml/Makefile.am
+++ b/ocaml/Makefile.am
@@ -98,7 +98,7 @@ if HAVE_OCAMLDOC
 noinst_DATA += html/index.html
 
 html/index.html: $(srcdir)/guestfs.mli $(srcdir)/guestfs.ml
-	-$(OCAMLDOC) -d html -html $^
+	-$(OCAMLFIND) ocamldoc -d html -html $^
 
 endif
 
-- 
2.5.0

Miscellaneous improvements to the ocamldoc:

 - Generate more sub-headings.

 - Document the object-oriented API.

 - Use a common function to generate the doc for module and OO APIs.
---
 generator/ocaml.ml | 84 +++++++++++++++++++++++++++++++-----------------------
 1 file changed, 49 insertions(+), 35 deletions(-)

diff --git a/generator/ocaml.ml b/generator/ocaml.ml
index 465df3c..2be3b7e 100644
--- a/generator/ocaml.ml
+++ b/generator/ocaml.ml
@@ -60,6 +60,8 @@ let rec generate_ocaml_mli ()      (see the end of this file
and {!guestfs})
     which is functionally completely equivalent, but is more compact. *)
 
+(** {3 Handles} *)
+
 type t
 (** A [guestfs_h] handle. *)
 
@@ -88,6 +90,8 @@ val close : t -> unit
     unreferenced, but callers can call this in order to provide
     predictable cleanup. *)
 
+(** {3 Events} *)
+
 type event  ";
   List.iter (
@@ -125,6 +129,8 @@ val event_to_string : event list -> string
 (** [event_to_string events] returns the event(s) as a printable string
     for debugging etc. *)
 
+(** {3 Errors} *)
+
 val last_errno : t -> int
 (** [last_errno g] returns the last errno that happened on the handle [g]
     (or [0] if there was no errno).  Note that the returned integer is the
@@ -149,41 +155,45 @@ module Errno : sig
   pr "\
 end
 
+(** {3 Structs} *)
+
 ";
   generate_ocaml_structure_decls ();
 
+  pr "\
+
+(** {3 Actions} *)
+
+";
+
+  let generate_doc ?(indent = "") f +    if is_documented f then (
+      let has_tags = ref false in
+
+      pr "%s(** %s" indent f.shortdesc;
+      (match f.deprecated_by with
+       | None -> ()
+       | Some replacement ->
+          has_tags := true;
+          pr "\n\n    @deprecated Use {!%s} instead" replacement
+      );
+      (match version_added f with
+       | None -> ()
+       | Some version ->
+          has_tags := true;
+          pr "\n\n    @since %s" version
+      );
+      if !has_tags then
+        pr "\n";
+      pr "%s *)\n" indent;
+    )
+  in
+
   (* The actions. *)
   List.iter (
-    fun ({ name = name; style = style; deprecated_by = deprecated_by;
-          non_c_aliases = non_c_aliases;
-          shortdesc = shortdesc } as f) ->
-      let need_doc = is_documented f in
-
-      if not need_doc then
-        pr "(**/**)\n";
-
+    fun ({ name = name; style = style; non_c_aliases = non_c_aliases } as f)
->
       generate_ocaml_prototype name style;
-
-      if need_doc then (
-        let has_tags = ref false in
-
-        pr "(** %s" shortdesc;
-        (match deprecated_by with
-         | None -> ()
-         | Some replacement ->
-             has_tags := true;
-             pr "\n\n    @deprecated Use {!%s} instead" replacement
-        );
-        (match version_added f with
-        | None -> ()
-        | Some version ->
-             has_tags := true;
-             pr "\n\n    @since %s" version
-        );
-        if !has_tags then
-          pr "\n";
-        pr " *)\n";
-      );
+      generate_doc f;
 
       (* Aliases. *)
       List.iter (
@@ -192,9 +202,6 @@ end
           generate_ocaml_prototype alias style;
       ) non_c_aliases;
 
-      if not need_doc then
-        pr "(**/**)\n";
-
       pr "\n";
   ) external_functions_sorted;
 
@@ -223,23 +230,30 @@ end
 
 class guestfs : ?environment:bool -> ?close_on_exit:bool -> unit ->
object
   method close : unit -> unit
+  (** See {!Guestfs.close} *)
   method set_event_callback : event_callback -> event list ->
event_handle
+  (** See {!Guestfs.set_event_callback} *)
   method delete_event_callback : event_handle -> unit
+  (** See {!Guestfs.delete_event_callback} *)
   method last_errno : unit -> int
+  (** See {!Guestfs.last_errno} *)
   method ocaml_handle : t
+  (** Return the {!Guestfs.t} handle *)
 ";
 
   List.iter (
-    fun { name = name; style = style; non_c_aliases = non_c_aliases } ->
+    fun ({ name = name; style = style; non_c_aliases = non_c_aliases } as f)
->
       (match style with
       | _, [], _ ->
         pr "  method %s : " name;
         generate_ocaml_function_type ~extra_unit:true style;
-        pr "\n"
+        pr "\n";
+        generate_doc ~indent:"  " f
       | _, (_::_), _ ->
         pr "  method %s : " name;
         generate_ocaml_function_type style;
-        pr "\n"
+        pr "\n";
+        generate_doc ~indent:"  " f
       );
       List.iter (fun alias ->
         pr "  method %s : " alias;
-- 
2.5.0

On Wednesday 30 September 2015 10:19:10 Richard W.M. Jones
wrote:
> Miscellaneous improvements to the ocamldoc:
> 
>  - Generate more sub-headings.
> 
>  - Document the object-oriented API.
> 
>  - Use a common function to generate the doc for module and OO APIs.
> ---
Mostly OK, except ...
> +  let generate_doc ?(indent = "") f > +    if is_documented f
then (
> +      let has_tags = ref false in
> +
> +      pr "%s(** %s" indent f.shortdesc;
> +      (match f.deprecated_by with
> +       | None -> ()
> +       | Some replacement ->
> +          has_tags := true;
> +          pr "\n\n    @deprecated Use {!%s} instead" replacement
> +      );
> +      (match version_added f with
> +       | None -> ()
> +       | Some version ->
> +          has_tags := true;
> +          pr "\n\n    @since %s" version
> +      );
> +      if !has_tags then
> +        pr "\n";
> +      pr "%s *)\n" indent;
> +    )
Unfortunately, this is not enough to hide the internal functions from
the API doc, but they need be enclosed by

(**/**)
val to_not_be_documented = ...
(**/**)

See also a0892aa29e92bc906a011faca84befe58f0265bc.

Thanks,
-- 
Pino Toscano

On Wednesday 30 September 2015 10:19:09 Richard W.M. Jones
wrote:
> Using 'ocamlfind ocamldoc' is much faster than running
'ocamldoc'
> directly, because ocamlfind will run the native code program
> 'ocamldoc.opt' if it is available.
> 
> This change approximately halves the time taken to compile the ocaml
> bindings.
LGTM.

Thanks,
-- 
Pino Toscano