annotating nested modules with ocamldoc

annotating nested modules with ocamldoc

[Ian Zimmerman]

Given the following files:

(* Foo.mli *)

module type BOO = sig
  (** workaround: put documentation here *)
  val boo : int -> int
end

module Boo : BOO

(* Foo.mli ends *)




(* Foo.ml *)

let internal_goo i = i + 1

module type BOO = sig
  val boo : int -> int
end

module Boo : BOO = struct
  let boo i = internal_goo (i + 1)
end

(* Foo.ml ends *)


how do I produce an ocamldoc set *with* Foo.Boo.boo but *without*
Foo.internal_goo ?

So far, the only way I've found is to only process the mli file with
ocamldoc and attach an annotation in the signature in the indicated
place, but that is awkward when I want to make a cross-reference (I
have to reference the signature instead of the structure).  The
problem is that when processing a ml file, the granularity of what is
included is one of two extremes: either everything, or just stuff
that's declared in the corresponding mli file, and the latter by
definition excludes members of modules :-(

Re: [Caml-list] annotating nested modules with ocamldoc

[Philippe Wang]

Le 6 janv. 07 à 16:22, Ian Zimmerman a écrit :

> Given the following files:
>
> (* Foo.mli *)
>
> module type BOO = sig
>  (** workaround: put documentation here *)
>  val boo : int -> int
> end
>
> module Boo : BOO
>
> (* Foo.mli ends *)
>
>
>
>
> (* Foo.ml *)
>
> let internal_goo i = i + 1
>
> module type BOO = sig
>  val boo : int -> int
> end
>
> module Boo : BOO = struct
>  let boo i = internal_goo (i + 1)
> end
>
> (* Foo.ml ends *)
>
>
> how do I produce an ocamldoc set *with* Foo.Boo.boo but *without*
> Foo.internal_goo ?
>
> So far, the only way I've found is to only process the mli file with
> ocamldoc and attach an annotation in the signature in the indicated
> place, but that is awkward when I want to make a cross-reference (I
> have to reference the signature instead of the structure).  The
> problem is that when processing a ml file, the granularity of what is
> included is one of two extremes: either everything, or just stuff
> that's declared in the corresponding mli file, and the latter by
> definition excludes members of modules :-(


I suggest you to use The Stop special comment   (**/**) in the .ml file.

(ocaml reference manual, section 15.2.2 )

Cheers,
Philippe Wang
   mail(at)philippewang.info

Re: [Caml-list] annotating nested modules with ocamldoc

[Ian Zimmerman]

On 1/6/07, Philippe Wang <lists@philippewang.info> wrote:

> I suggest you to use The Stop special comment   (**/**) in the .ml file.
>
> (ocaml reference manual, section 15.2.2 )

I know about that mechanism, it doesn't help in this situation.  Note
that the definition of boo uses internal_goo, so internal_goo must
come before module Boo in the source file.  Where would I put the stop
comment to achieve what I want?

Re: [Caml-list] annotating nested modules with ocamldoc

[Philippe Wang]

Le 6 janv. 07 à 16:57, Ian Zimmerman a écrit :

> On 1/6/07, Philippe Wang <lists@philippewang.info> wrote:
>
>> I suggest you to use The Stop special comment   (**/**) in the .ml  
>> file.
>>
>> (ocaml reference manual, section 15.2.2 )
>
> I know about that mechanism, it doesn't help in this situation.  Note
> that the definition of boo uses internal_goo, so internal_goo must
> come before module Boo in the source file.  Where would I put the stop
> comment to achieve what I want?

Like that :

module Misc =
struct
    (**/**)
    let internal_goo = succ
end

open Misc


For example...

Well, maybe you don't even need to use (**/**) as you can define such  
a local module without exporting it in the .mli file...

Does it help ?

Cheers,
Philippe Wang

Re: [Caml-list] annotating nested modules with ocamldoc

[Daniel Bünzli]

Le 6 janv. 07 à 16:57, Ian Zimmerman a écrit :

> Where would I put the stop comment to achieve what I want?

The stop comment is a toggle, if you issue it again it starts  
documenting again (which btw does not correspond to what's described  
in the manual).

(**/**)
val internal_goo : t
(**/**)

Best,

Daniel

Re: [Caml-list] annotating nested modules with ocamldoc

[Ian Zimmerman]

On 1/6/07, Daniel Bünzli <daniel.buenzli@epfl.ch> wrote:

> The stop comment is a toggle, if you issue it again it starts
> documenting again (which btw does not correspond to what's described
> in the manual).
>
> (**/**)
> val internal_goo : t
> (**/**)
>

Aha!  Thanks indeed.