From mboxrd@z Thu Jan 1 00:00:00 1970 Received: (from majordomo@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id WAA16274; Sun, 13 May 2001 22:24:19 +0200 (MET DST) X-Authentication-Warning: pauillac.inria.fr: majordomo set sender to owner-caml-list@pauillac.inria.fr using -f Received: (from weis@localhost) by pauillac.inria.fr (8.7.6/8.7.3) id WAA16343 for caml-list@pauillac.inria.fr; Sun, 13 May 2001 22:24:18 +0200 (MET DST) Received: from concorde.inria.fr (concorde.inria.fr [192.93.2.39]) by pauillac.inria.fr (8.7.6/8.7.3) with ESMTP id UAA02754 for ; Wed, 9 May 2001 20:17:45 +0200 (MET DST) Received: from localhost.localdomain (jimbo151.zip.com.au [202.7.67.151]) by concorde.inria.fr (8.11.1/8.10.0) with ESMTP id f49IHcX18664; Wed, 9 May 2001 20:17:39 +0200 (MET DST) Received: from ozemail.com.au (IDENT:root@localhost [127.0.0.1]) by localhost.localdomain (8.9.3/8.8.7) with ESMTP id EAA13950; Thu, 10 May 2001 04:17:31 +1000 Message-ID: <3AF989BA.7C9E5E8F@ozemail.com.au> Date: Thu, 10 May 2001 04:17:30 +1000 From: John Max Skaller X-Mailer: Mozilla 4.7 [en] (X11; I; Linux 2.2.12-20 i686) X-Accept-Language: en MIME-Version: 1.0 To: Markus Mottl CC: David Mentre , Fabrice Le Fessant , caml-list@inria.fr Subject: Re: [Caml-list] Re: About documentation tools References: <15094.25994.675673.222337@cremant.inria.fr> <20010509125858.B28402@miss.wu-wien.ac.at> <20010509151828.A16874@miss.wu-wien.ac.at> Content-Type: text/plain; charset=us-ascii Content-Transfer-Encoding: 7bit Sender: owner-caml-list@pauillac.inria.fr Precedence: bulk Markus Mottl wrote: > It's a > reasonable assumption that Xavier and the others prefer hacking away on > new compiler features rather than such things and would need engineers > for more earthly tasks. I don't think this is as reasonable as you say. In principle, an Ocaml module interface should specify semantics. However, Ocaml doesn't include language constructs to specify the axioms the interface obeys: they have to be given as comments. Some languages, like Eiffel, actually support constructions for specifying function preconditions. So it actually makes sense to allow axioms to be specifed in a module interface _as part of the language_, even if it is only a special form of comment containing vague natural language text. I'm not suggesting this, only that Xavier may be more interested than you think in formalising a documentation protocol designed to supply the missing information. > I don't know Java (and therefore javadoc) well enough to judge this > (maybe at least javadoc is well-designed), but I'd surely argue against > taking up inferior approaches if we can do things the right way right > from the start. Ocamlweb -- and Javadoc -- are 'inferior' approaches. A fully fledged literate programming tool is a better solution. But it requires a 'heavy' committment to literate programming many are not willing to make. So a more lightweight approach is a reasonable compromise. I note that many Java programmers I have talked to think Javadoc is one of the best things about Java. :-) I also note that perldoc has served Perl users well. Python's doc strings do not work as well. A C++ system I have worked on used a convention suitable for generating 'man' pages. Unlike proper LP tools, these things never generate enough of the right documentation. But at least they generate _some_, which is better than none at all. Even though I use a powerful LP tool, I'd adhere to an ocaml convention, and I'd also use the standard ocamldoc tool in addition to the LP tool I use. One comment though: a modern tool must generate HTML, _directly_. It is not good enough to generate LaTeX, and then translate it into HTML. Please, I want _one_ tool, not a long complicated error prone chain to add to my existing chain :-) -- John (Max) Skaller, mailto:skaller@maxtal.com.au 10/1 Toxteth Rd Glebe NSW 2037 Australia voice: 61-2-9660-0850 checkout Vyper http://Vyper.sourceforge.net download Interscript http://Interscript.sourceforge.net ------------------- To unsubscribe, mail caml-list-request@inria.fr. Archives: http://caml.inria.fr