From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.1.3 (2006-06-01) on yquem.inria.fr X-Spam-Level: X-Spam-Status: No, score=0.0 required=5.0 tests=AWL autolearn=disabled version=3.1.3 X-Original-To: caml-list@yquem.inria.fr Delivered-To: caml-list@yquem.inria.fr Received: from mail2-relais-roc.national.inria.fr (mail2-relais-roc.national.inria.fr [192.134.164.83]) by yquem.inria.fr (Postfix) with ESMTP id BA61EBBCA; Mon, 5 May 2008 11:43:49 +0200 (CEST) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AgECAL9zHkjAXQImiGdsb2JhbACBU5AiAQEBDyCXXg X-IronPort-AV: E=Sophos;i="4.27,437,1204498800"; d="ml'?scan'208";a="10389622" Received: from discorde.inria.fr ([192.93.2.38]) by mail2-smtp-roc.national.inria.fr with ESMTP; 05 May 2008 11:43:49 +0200 Received: from mail1-relais-roc.national.inria.fr (mail1-relais-roc.national.inria.fr [192.134.164.82]) by discorde.inria.fr (8.13.6/8.13.6) with ESMTP id m459hmvL004106 (version=TLSv1/SSLv3 cipher=RC4-SHA bits=128 verify=OK); Mon, 5 May 2008 11:43:49 +0200 X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AgECAL9zHkjBMjI+iGdsb2JhbACBU5AiAQEBDyCXXg X-IronPort-AV: E=Sophos;i="4.27,437,1204498800"; d="ml'?scan'208";a="11844964" Received: from haydn2002.u-bourgogne.fr ([193.50.50.62]) by mail1-smtp-roc.national.inria.fr with ESMTP; 05 May 2008 11:43:49 +0200 Received: from alcazar.inria.fr (guesdon@hydroptere.u-bourgogne.fr [193.52.236.56]) by haydn2002.u-bourgogne.fr (8.13.8/8.13.8) with ESMTP id m459hmUB026213; Mon, 5 May 2008 11:43:48 +0200 Date: Mon, 5 May 2008 11:48:16 +0200 From: Maxence Guesdon To: caml-list@inria.fr Subject: Re: [Caml-list] Documenting submodules ? Message-ID: <20080505114816.6638fd36@alcazar.inria.fr> In-Reply-To: <1209978725.6431.18.camel@Blefuscu> References: <1209593864.6823.36.camel@Blefuscu> <1209975770.6431.5.camel@Blefuscu> <20080505103513.6f48d8fc@alcazar.inria.fr> <1209978725.6431.18.camel@Blefuscu> X-Mailer: Claws Mail 3.4.0 (GTK+ 2.12.9; i486-pc-linux-gnu) Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="MP_/.86geE5GE3O/kMRhhhg6ehs" X-Miltered: at discorde with ID 481ED6D4.000 by Joe's j-chkmail (http://j-chkmail . ensmp . fr)! X-Miltered: at haydn02.u-bourgogne.fr with ID 481ED6D4.002 by Joe's j-chkmail (http://j-chkmail.ensmp.fr)! X-Scanned-By: MIMEDefang 2.63 on 193.50.50.62 X-Spam: no; 0.00; maxence:01 guesdon:01 maxence:01 guesdon:01 submodules:01 univ-orleans:01 0200,:01 ocamldoc:01 ocamldoc:01 work-around:01 compilation:01 ocamlc:01 odoc:01 odoc:01 cmo:01 X-Attachments: type="text/x-ocaml" name="odoc_example.ml" name="odoc_example.ml" --MP_/.86geE5GE3O/kMRhhhg6ehs Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Content-Disposition: inline On Mon, 05 May 2008 11:12:05 +0200 David Teller 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 > > 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 --MP_/.86geE5GE3O/kMRhhhg6ehs Content-Type: text/x-ocaml; name=odoc_example.ml Content-Transfer-Encoding: 7bit Content-Disposition: attachment; filename=odoc_example.ml 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);; --MP_/.86geE5GE3O/kMRhhhg6ehs--