Re: Documenting Large Prolog Systems

From: Gregory Bourassa (bourassa_nospam_at_magma.ca)
Date: 03/01/05

  • Next message: Bart Demoen: "Re: Newbie question about list" 
    Date: Mon, 28 Feb 2005 22:39:00 -0500 (EST)

    On Sun, 27 Feb 2005 21:50:17 -0800, David Poole wrote:

    David,

    I have documented large Prolog systems, and it is not too hard. That said,
    any of the off-the-shelf documentation tools like UML will be tortured if you
    try to use them -- they have no representation for backtracking, failure,
    unification, and multiple solutions from backtracking.

    Your best bet is to assume an "Encyclopoedia of predicates" approach and
    document the main predicates -- not the helpers which are only there to
    support interesting predicates. For each predicate or relation you should
    document:
            Name
            Arity
            Known flow patterns (bound on call, free on call for each
    argument)...e.g. (var, var, nonvar) (var,var,var) (novar,var,nonvar), or
    (free,free.bound) etc., or (i,i,o)...whatever notation you like as long as
    you do it.
            A comment for each flow pattern
            Some comments on the expected terms which can be passed as arguments
    -- this is very important to maintainers. Let's be practical, rarely can
    every argument can be of every functor type and still work!
            Whether or not failure can happen
            What is returned on multiple entries due to backtracking
            Whether or not the predicate can backtrack (deterministic or
    nondeterministic)
            Whether or not you can expect any system-level exceptions and what
    they might be
            What data (facts) if any are expected to exist in the environment at
    run-time for the predicate to succeed

    ...and probably other things, but they escape my memory just now -- the above
    constitutes a good start

    If you can, partition the system into "packages". There is usually a set of
    list-handling and other predicates which are just "utilities" used
    everywhere, then there will be other modules or packages which you can
    recognise, which do things like file access, IP communications,
    pretty-printing, graphics, and finally the various parts of the core
    behaviour of your system.

    Let the rest of the project team know that the Prolog subsystem is
    meta-relational and meta-object-oriented, so they will have to deal with
    your documentation as something more than they think they see -- they will
    think they are seeing something very like a C-language API. Don't stand
    for such complacency.

    Regards.

    Gregory Bourassa

    >Hi All,
    >What experiences do people have documenting large Prolog systems?
    >
    >We are looking for something more than predicate or module-level
    >documentation; a way for a new user to understand the structure of a
    >large Prolog system. Something like UML, but for relations not just
    >describing objects. Has anyone tried documenting a Prolog program in
    >UML? Our intuition is that this is not a good place to start, but I
    >thought I would ask about what are good places to start. Any experience
    >you have would be appreciated.
    >
    >The Prolog program we are using is part of a larger system that is being
    >documented in UML. I'd appreciate any feedback from anyone who has tried
    >to document large Prolog systems.
    >
    >Thanks,
    >David
    >
    >p.s. I asked about this in the SWIPL mailing list, but with no answer.
    >
    >
    >--
    >David Poole, Office: +1 (604) 822-6254
    >Professor, Fax: +1 (604) 822-5485
    >Department of Computer Science, poole@cs.ubc.ca
    >University of British Columbia, http://www.cs.ubc.ca/spider/poole
    >Vancouver, B.C., Canada V6T 1Z4 ftp://ftp.cs.ubc.ca/ftp/local/poole

  • Next message: Bart Demoen: "Re: Newbie question about list"

    Relevant Pages

    • Re: Documenting Large Prolog Systems
      ... abstraction hierarchy of subsystems and modules, ... organized by subsystem. ... documentation purposes are perhaps like the "packages" Gregory Bourassa ... >> What experiences do people have documenting large Prolog systems? ...
      (comp.lang.prolog)
    • Re: PHP and Diagram Tool
      ... UML isn't that simple at all. ... It may well be that the OP wants more detailed documentation and a few relationships in which case diagrams are _not_ the way to go at all. ... All-in-all I would rather spend the time others spend on pretty pictures, doing written documentation and exercise code. ...
      (comp.lang.php)
    • Re: TDD: Test-Driven Design or Test-Driven Development?
      ... >> how to improve the code to express their intent. ... >ancillary documentation? ... >> diagrams they drew. ... >> UML instead of expressing themselves in code. ...
      (comp.object)
    • Re: Why is Delphi more RAD than C++ ?
      ... question your preference not to use UML - like you say, ... class diagram I had just done and realized there was a class in my ... plain useless. ... documentation for them. ...
      (borland.public.delphi.non-technical)
    • Re: SWI-Prolog: Undocumented predicates?
      ... use the native Windows version. ... meant also to change the data file. ... Why isn't readln/1 mentioned neither in the book nor in the documentation? ... Are there other helpful but undocumented predicates? ...
      (comp.lang.prolog)