[editor-hints-devel] My thoughts about markup and docstrings

[Tobias C. Rittweiler]

David Lichteblau <david at lichteblau.com> writes:

> (annotate-documentation (foo function)
>   (:argument a "This is the important argument of type BAR")
>   (:argument b "This is the BAZ being frobbed in some special way")
>   (:return-value "random junk of type QUUUX")
>   (:condition big-mistake-error)
>   (:see-function the-other-function))

This looks all good. I do have some suggestions:

  * In the documentation of ANNOTATE-DOCUMENTATION, do not talk about
    "forms", but about "clauses".

  * Add a (:RESTART) clause.

  * Instead of (:SEE-ALSO-FUNCTION) (:SEE-ALSO-TYPE) &c, make it
    (:SEE-ALSO :FUNCTION) and so on. Where the second clause argument is
    any symbol, and where this set of symbols can be extended.

  * For each symbol given in the clauses perform a consistency check,
    i.e. for (:CONDITION FOO) if FOO really names a condition, if not
    signal a style-warning. 

    (It should probably be possible to turn this behaviour off by
    setting some special variable to NIL at compilation-time.)

I experimented with a sexp-style documentation format, too. See [*].


> Parse-docstrings' main API function is DOCUMENTATION*, which is like
> DOCUMENTATION, but
>   - returns CLOS objects instead of a string
>   - uses the annotation macro instead of (just) the docstring

I'd call it STRUCTURED-DOCUMENTATION, ELABORATE-DOCUMENTATION, or
similiar.


[*] - 

   http://common-lisp.net/websvn/filedetails.php?repname=editor-hints&path=%2Ftrunk%2Feditor-hints%2Fdoc%2Fdefreadtable-clhs-page.lisp&rev=0&sc=0