Documenting submodules ?

Documenting submodules ?

[David Teller]

   Dear list,

As mentioned previously, I'm working on a derivative of ExtLib
(promised, I'll submit the changes within a few days). I've put together
most of the features I want for now, but I'm faced with a problem of
documentation. Essentially, I have a few big modules containing each a
few smaller modules -- each smaller module being defined in one file. 

When invoking ocamldoc, either directly or through ocamlbuild + .odocl,
the generated documentation only contains the name of modules, without
any of the comments or even the values.

Is there any ocamldoc plug-in or ocamlbuild plug-in or anything else
that could help me document my code without having to rewrite everything
and/or to copy and paste thousands of lines of .mli ?

Cheers,
 David

-- 
David Teller
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Documenting submodules ?

[Arnaud Spiwack]

As far as I'm aware, the HTML output of ocamldoc documents submodules as 
hyperlinks. By clicking on them you then get to a documentation of the 
submodule itself. This is already something.


Arnaud Spiwack

David Teller a écrit :
>    Dear list,
>
> As mentioned previously, I'm working on a derivative of ExtLib
> (promised, I'll submit the changes within a few days). I've put together
> most of the features I want for now, but I'm faced with a problem of
> documentation. Essentially, I have a few big modules containing each a
> few smaller modules -- each smaller module being defined in one file. 
>
> When invoking ocamldoc, either directly or through ocamlbuild + .odocl,
> the generated documentation only contains the name of modules, without
> any of the comments or even the values.
>
> Is there any ocamldoc plug-in or ocamlbuild plug-in or anything else
> that could help me document my code without having to rewrite everything
> and/or to copy and paste thousands of lines of .mli ?
>
> Cheers,
>  David
>
>   

Re: [Caml-list] Documenting submodules ?

[Julien Signoles]

> When invoking ocamldoc, either directly or through ocamlbuild + .odocl,
> the generated documentation only contains the name of modules, without
> any of the comments or even the values.

Usually ocamldoc works fine with submodule:

===== sub.ml
(** This is {!A}. It contains a properly-documented submodule {!A.B} and a
     single value {!A.a}. *)
module A = struct

   (** This is {!B}. It contains a single value {!B.b}. *)
   module B = struct let b = 1 end

   let a = 0

end
=====

$ ocamldoc -version
Ocamldoc 3.10.1
$ ocamldoc -html sub.ml

Hope this helps,
Julien Signoles

Re: [Caml-list] Documenting submodules ?

[David Teller]

Let me rephrase:

Case 1)

==== sub.ml
(** This is [Sub] *)

type t
 (** This is [Sub.t]*)

==== main.ml
module Sub = Sub

Running ocamldoc drops the comments of sub.ml .

Case 2)

==== sub.ml
module SubSub = struct
  type t
  (** This is [SubSub.t] *)
end

==== main.ml
module SubSubSub = Sub.SubSub


Running ocamlc drops the comments of sub.ml -- and the very existence of
SubSub.t.

Cheers,
 David

On Mon, 2008-05-05 at 10:11 +0200, Julien Signoles wrote:
> > When invoking ocamldoc, either directly or through ocamlbuild + .odocl,
> > the generated documentation only contains the name of modules, without
> > any of the comments or even the values.
> 
> Usually ocamldoc works fine with submodule:
> 
> ===== sub.ml
> (** This is {!A}. It contains a properly-documented submodule {!A.B} and a
>      single value {!A.a}. *)
> module A = struct
> 
>    (** This is {!B}. It contains a single value {!B.b}. *)
>    module B = struct let b = 1 end
> 
>    let a = 0
> 
> end
> =====
> 
> $ ocamldoc -version
> Ocamldoc 3.10.1
> $ ocamldoc -html sub.ml
> 
> Hope this helps,
> Julien Signoles
> 
-- 
David Teller
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Documenting submodules ?

[Maxence Guesdon]

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

> Let me rephrase:
> 
> Case 1)
> 
> ==== sub.ml
> (** This is [Sub] *)
> 
> type t
>  (** This is [Sub.t]*)
> 
> ==== main.ml
> module Sub = Sub
> 
> Running ocamldoc drops the comments of sub.ml .

Indeed, ocamldoc does not use the comment of sub.ml in the page generated
for main.ml. This is normal behaviour. You could comment the creation of the
Sub module (i.e. Main.Sub) by putting a comment around
  module Sub = Sub

> Case 2)
> 
> ==== sub.ml
> module SubSub = struct
>   type t
>   (** This is [SubSub.t] *)
> end
> 
> ==== main.ml
> module SubSubSub = Sub.SubSub
> 
> 
> Running ocamlc drops the comments of sub.ml -- and the very existence of
> SubSub.t.

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.

Regards,

Maxence

Re: [Caml-list] Documenting submodules ?

[David Teller]

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.

> 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 ?

Cheers,
 David

-- 
David Teller
 Security of Distributed Systems
  http://www.univ-orleans.fr/lifo/Members/David.Teller
 Angry researcher: French Universities need reforms, but the LRU act brings liquidations. 

Re: [Caml-list] Documenting submodules ?

[Maxence Guesdon]

[-- 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);;