Re: ocamldoc generation and packed files

[Anil Madhavapeddy <anil@xxxxxxxxxx>]

That tool will be very useful! I've committed the 'make doc' target. The output 
is still pretty dirty as we don't use the documentation tags properly, but I'll 
go through adding .mli files and adding proper documentation on the more stable 
interfaces.

It would be quite nice to eventually have a single documentation output for all 
the backends, with an addition section saying 'only present in Xen' or 'only 
present in Node'. I think that should be possible by parsing the ocamldoc dump 
outputs, but something for the future!

Anil

On 27 Jul 2011, at 16:56, Thomas Gazagnaire wrote:

> We have as well a program which pack together ML files (and is able to 
> functorize packs as well...) it is not released yet, but I guess we can 
> open-source it shortly.
> 
> But I think overriding the default rule for ocamldoc+pack in ocamlbuild is 
> sufficient for now on so you should push your patch :-)
> 
> Thomas
> 
> On Jul 27, 2011, at 5:36 PM, Anil Madhavapeddy wrote:
> 
>> I'd really like to generate ocamldoc (HTML/PDF) of all the various libraries 
>> so that it's easier to learn Mirage (and support editor auto-completion, 
>> etc).
>> 
>> The big problem is that ocamldoc doesn't support packed modules, and we use 
>> packing quite extensively (in Net, Http, Block, etc).
>> 
>> So I've hacked up an ocamlbuild target that concats together the *source* ML 
>> files from an .mlpack and uses that to generate the ocamldoc for the 
>> standard library, with one set of HTML files generated per backend (Xen, 
>> Net-Direct, Net-Socket, and so on).
>> 
>> The issue is that these rules are a little grim: everywhere where we have a 
>> .mlpack file at the moment, we need to override that rule to generate a 
>> concatenated ML file that is used for ocamldoc (but not for actual 
>> compilation, since line numbers get lost since those aren't preserved when 
>> converting from ML files into a single big one).
>> 
>> Does anyone have a better solution for ocamldoc and packed files? All of the 
>> grimness here is hidden away in the ocamlbuild rules, so I'm inclined to 
>> just commit this patch, and perhaps see about adding -pack support into 
>> ocamldoc at a later stage (there's an open bug in Mantis somewhere). 
>> 
>> Dave, do you use pack in XAPI, and/or ocamldoc?  I wonder if everyone else 
>> (like Core) also have their own swanky 'cat ML files into one' script too...
>> 
>> -anil
>