4:19 a.m.
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