Re: [Caml-list] Documenting submodules ?

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

[-- Attachment #1: Type: text/plain, Size: 1947 bytes --]

On Mon, 05 May 2008 11:12:05 +0200
David Teller <David.Teller@univ-orleans.fr> wrote:

> On Mon, 2008-05-05 at 10:35 +0200, Maxence Guesdon wrote:
> > Indeed, ocamldoc does not use the comment of sub.ml in the page generated
> > for main.ml. This is normal behaviour. 
> 
> I'm aware that it's the normal behaviour of ocamldoc. I'm just looking
> for a work-around or a plug-in.
> 
> > You could comment the creation of the
> > Sub module (i.e. Main.Sub) by putting a comment around
> >   module Sub = Sub
> 
> I wrote that in my first post :)
> More seriously, it's ok if I have only one or two modules. But if I want
> to comment both the creation of Sub and the actual contents of Sub, it's
> not really a good method. Even more so since I have 70+ modules
> developed separately, which I attempt to present with a consistent
> Java-style package hierarchy. That would mean copying and pasting about
> 9000+ lines of code for the moment, with more coming, and nasty bugs
> lurking whenever the source packages are updated.

Sorry, I did not re-read your original post before replying. Here is
attached a custom generator that, for each module defined by the form
 module A = B
replace the comment information of A by the comment information of B, then
call the regular HTML generator. Of course, you can adapt it to do this only
for some module of your choice.

Compilation:
  ocamlc -c -I +ocamldoc odoc_example.ml

Usage:
  ocamldoc [options] -g odoc_example.cmo <your .ml{,i} files>


> > This is normal behaviour too. You're redefining a module here, and the
> > way it is defined is reflected by the html code generated by ocamldoc, with
> > a link on the Sub.SubSub page.
> 
> I have a link to an empty Sub.SubSub page. Is that normal behaviour ?

This works well for me. The page contains:
                                                    Module Sub.SubSub

module SubSub: sig .. end
  

type t

   This is SubSub.t

Regards,

Maxence

[-- Attachment #2: odoc_example.ml --]
[-- Type: text/x-ocaml, Size: 927 bytes --]

open Odoc_info;;
open Module;;

class my_generator =
  object(self)
    inherit Odoc_html.html as html

    method generate modules =
      let all_modules = Odoc_info.Search.modules modules in
      let f m =
        match m.m_kind with
          Module_alias a ->
            begin
              match a.ma_module with
                None -> () (* module not resolved in cross-reference stage *)
              | Some aliased ->
                  (* replace the info on module by info on the aliased *)
                  let info = match aliased with
                      Mod m -> m.m_info
                    | Modtype mt -> mt.mt_info
                  in
                  m.m_info <- info
            end
        | _  -> ()
      in
      List.iter f all_modules;
      html#generate modules
  end;;

let doc_generator = ((new my_generator) :> Args.doc_generator);;
let _ = Args.set_doc_generator (Some doc_generator);;