[Libguestfs] [PATCH 2/2] ocaml: Improve ocamldoc.

[Richard W.M. Jones]

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