[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Document formatting in Scheme
Noel Welsh <noelwelsh@yahoo.com> writes:
>One half of the problem is API documentation.
...
I'd just like to mention a somewhat different approach for this:
literate programming. There are programming language-independent tools
for this (nowebm seems to be a good and simple one), and the markup
language is usually some form of TeX (which can, of course, be
converted to HTML, good-quality PostScript, etc.). See the
comp.programming.literate FAQ for pointers to more information on the
tools and such.
The advantages of this approach are that it can be used for all
describing of source code (not just the external interface) and that
the tools and markup language already exist (and there may be people
who have already used the tools with another language, so they don't
need to learn yet another syntax for documenting code).
Disadvantages are that the syntax is usually not very "Schemish" (not
S-expressions), and perhaps that literate programming doesn't really
offer a complete solution to API documentation: you usually still need
to create a smaller sub-language for specifying the API of functions,
because literate programming seems to be more of an informal approach
to documenting software. (At least that's what I've gathered from
reading Knuth's _TeX: The Program_: there is very little API
documentation, but lots of documentation on how and why the code
works. Perhaps other people use it differently, I don't really know.)
Just thought I'd mention it. I have a feeling that it would be more
useful to create a language-independent approach to API documentation
than to write something that only works for Scheme...
But if you are writing something for Scheme only, I'd suggest making
it a language feature instead of things to put in comments. It would
be nice if you could, e.g., ask the interpreter for the documentation
to a particular function, kind of like many Lisps do. And I think it's
cleaner to leave comments as informal descriptions. But I don't think
Lisp docstrings by themselves are enough: one should also specify a
machine-readable format for what to put in the docstrings.
I once had an idea of splitting up the documentation for arguments,
like:
(define (fun <argname> <argdescription> ...)
<return-value-description>
<docstring>
<body of function ...>)
For example:
(define (mergesort less-than? "a < predicate for ordering the elements"
lst "the list to sort") "the sorted list"
"Sorts the given list using Merge sort, in O(n log n) comparisons,
where n is (length lst)."
<body of function here ...>)
But I don't really like the way that syntax breaks up the argument
list, though it may be somewhat better than Javadoc's way of
requiring another copy of the argument list in the comments.
--
-=- Rjs -=- Riku.Saikkonen@hut.fi
"From cavern pale the moist moon eyes / the white mists that from earth arise /
to hide the morrow's sun and drip / all the grey day from each twig's tip."
-- J. R. R. Tolkien