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