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

[Richard W.M. Jones]

On Wed, Sep 30, 2015 at 02:58:12PM +0200, Pino Toscano wrote:
> 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.

Gotcha - I was wondering what those were for!  I will add them back.

Rich.

-- 
Richard Jones, Virtualization Group, Red Hat http://people.redhat.com/~rjones
Read my programming and virtualization blog: http://rwmj.wordpress.com
virt-df lists disk usage of guests without needing to install any
software inside the virtual machine.  Supports Linux and Windows.
http://people.redhat.com/~rjones/virt-df/