Re: [Caml-list] Two questions on OCamlDoc

[Maxence Guesdon <Maxence.Guesdon@inria.fr>]

On Tue, 02 Sep 2008 13:47:08 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

>      Hi everyone,

Hello,

>  I'm currently toying with OCamlDoc, with very little success. I'm
> attempting to do two things:
> * getting OCamlDoc to understand that some modules (which I can modify)
> contain the documentation for some other modules (which I can't) replace
> some modules with others
> * inlining the documentation for modules in modules which import those.
> 
> I need a little help.
> 
> Let me detail this.
> 
> *** Documentation replacement ***
> My project uses modules M_lib1, M_lib2... which come from a variety of
> libraries. For each of these modules, I have created  a module
> M_lib1_with_doc, M_lib2_with_doc, which imports the corresponding
> library module but tailors the documentation to my project. However, for
> technical reasons of mechanical generation, assuming that M_lib1 refers
> to M_lib2, M_lib1_with_doc still refers to M_lib2 instead of referring
> to M_lib2_with_doc. Consequently, when generating the documentation of
> M_lib1_with_doc, ocamldoc doesn't link the generated pages to the
> documentation of M_lib2_with_doc but rather attempts to link it to
> M_lib2 (and fails, as expected).
> 
> Now, I could rework the mechanical generation of my modules and in time,
> I will. However, for the moment, I'm looking for a purely OCamlDoc-based
> solution. I'd like to be able to ask OCamlDoc to please consider every
> reference to M_lib2 as actually meaning a reference to M_lib2_with_doc.
> 
> I have tried to override method [text#html_of_Ref], without much
> success. Is there a simple solution for this?

A simple way (but not always possible, due to name clashes) would be to
use some script to perform string substitution in generated html files; in
your example, replacing all "M_lib2" by "M_lib2_with_doc". you could indeed
try to do this by overriding the method html_of_Ref. What problem do you
encounter ?

Another way would be to use some "cat" commands to create new
"..._with_doc.ml" files, compile them and use your "..._with_doc.mli" as
documented interface.

> *** Inlining modules ***
> I have a few modules whose sole role is to include one or two existing
> modules. By default, when meeting [include], OCamlDoc, ocamldoc only
> generates a link from the container module to the inlined module. In
> this case, I'd rather want the whole documentation of each of these
> modules to be inlined. 
>
> Is that possible?

May be. You could try to override the method html_of_module_element so that,
when you encounter a Element_included_module, you search the real module by
its name and print its elements instead of just "include ...".

Does this help ?

Regards,

Maxence


-- 
Maxence Guesdon                           http://yquem.inria.fr/~guesdon/
Service Expérimentation et Développements https://devel.inria.fr/rocq/
INRIA Paris-Rocquencourt                  http://www.inria.fr/rocquencourt/