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 mail4-relais-sop.national.inria.fr (mail4-relais-sop.national.inria.fr [192.134.164.105]) by yquem.inria.fr (Postfix) with ESMTP id EE207BBC1 for ; Mon, 3 Mar 2008 10:03:56 +0100 (CET) X-IronPort-Anti-Spam-Filtered: true X-IronPort-Anti-Spam-Result: AgAAAFtOy0fAbSoIh2dsb2JhbACQcQEBAQgKKZoi X-IronPort-AV: E=Sophos;i="4.25,436,1199660400"; d="scan'208";a="23283742" Received: from einhorn.in-berlin.de ([192.109.42.8]) by mail4-smtp-sop.national.inria.fr with ESMTP; 03 Mar 2008 10:03:50 +0100 X-Envelope-From: oliver@first.in-berlin.de X-Envelope-To: Received: from einhorn.in-berlin.de (localhost [127.0.0.1]) by einhorn.in-berlin.de (8.13.6/8.13.6/Debian-1) with ESMTP id m2393n6w017297 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NOT) for ; Mon, 3 Mar 2008 10:03:49 +0100 Received: (from www-data@localhost) by einhorn.in-berlin.de (8.13.6/8.13.6/Submit) id m2393mEt017295 for caml-list@yquem.inria.fr; Mon, 3 Mar 2008 10:03:48 +0100 X-Authentication-Warning: einhorn.in-berlin.de: www-data set sender to oliver@first.in-berlin.de using -f Received: from dslb-088-073-098-054.pools.arcor-ip.net (dslb-088-073-098-054.pools.arcor-ip.net [88.73.98.54]) by webmail.in-berlin.de (IMP) with HTTP for ; Mon, 3 Mar 2008 10:03:48 +0100 Message-ID: <1204535028.47cbbef4afe38@webmail.in-berlin.de> Date: Mon, 3 Mar 2008 10:03:48 +0100 From: Oliver Bandel To: caml-list@yquem.inria.fr Subject: Re: documentation (Re: Re : [Caml-list] Not Rocket Science) References: <200803021041.55208.jon@ffconsultancy.com> <666572260803020346v3137bbd9t29900c2ca97c2dce@mail.gmail.com> <1204462441.47caa369bed13@webmail.in-berlin.de> In-Reply-To: <1204462441.47caa369bed13@webmail.in-berlin.de> MIME-Version: 1.0 Content-Type: text/plain; charset=ISO-8859-1 Content-Transfer-Encoding: 8bit User-Agent: Internet Messaging Program (IMP) 3.2.6 X-Scanned-By: MIMEDefang_at_IN-Berlin_e.V. on 192.109.42.8 X-Spam: no; 0.00; bandel:01 in-berlin:01 bandel:01 in-berlin:01 camlimages:01 lib:01 ocamldoc:01 ocamldoc:01 indirections:01 workarounds:01 plug-in:98 imho:01 oliver:01 oliver:01 caml-list:01 Zitat von Oliver Bandel : [...] > IMHO the biggest necessity is better documentation. > This also holds for a lot of OCaml-libraries, like > Camlimages and others. I didn't meant the standard lib... (...but possibly, because I now know how to use them?) > > It's fine to have the documentation showing all > types and values. > It's even better to explain, what modules can plugged in in which > other > modules, meaning here: which types of the modules in use fit > together. With ocamldoc for example it is possible to show the relations of the modules of a program, and to show which module uses which other module. (graphviz-output). This is a quite good idea. To have such a thing for the way, modules should/can be plugged together, determined by the custom types that are provided by the modules, would enhance readability and understanding of a documentation a lot! I'm not sure if this should be an additional function for ocamldoc; possibly one also could create dummy-applications that use modules in a way, so that plug-in possibilities can be shown with ocamldoc, when using the graphviz-option. But this are indirections/detours/workarounds. Possibly an new, added functionality of ocamldoc or another application could be used here. Or is ocamlbuild able to create such stuff? As I so far didn't used it, maybe someone knows if it can be used for such documentation-enhancements? Ciao, Oliver