Re: [was: generation of ocamldoc HTML documentation for libs (via cdbs)] OCaml policy for documentation
On Mon, 27 Aug 2007 06:18:34 +1000
skaller <skaller@users.sourceforge.net> wrote:
> On Sun, 2007-08-26 at 17:55 +0000, Sylvain Le Gall wrote:
>
> BTW: a note on Ocamldoc .. unless it has been fixed, this
> program is still bugged and cannot generate proper documentation.
Easy troll. I agree OCamldoc suffers some limitations in particular when
handling "open" and "include" directives, but I find it satisfying most of
the time.
> In particular, whilst variant tags can be annotated, no documentation
> is generated for polymorphic variant tags.
Indeed.
> It is also unclear what happens when camlp4/5 is used.
It's very simple: If the preprocessor used does not keep comments, or change
their locations in the ocaml-syntax output, the comments are lost.
>
> Functions shared by implementations in a library
> may exist which are not intended to be public, there should be
> some standard annotation for this (ocamldoc still documents
> the function, but with a standardised 'implementation detail'
> annotation).
>
> Also I have no idea what happens if -pack is used (a poorly
> thought out feature IMHO).
There is no support -pack in ocamldoc, that is there is no way to prefix
everything, is a set of modules, with a given name.
--
Maxence Guesdon
--
Reply to: