[Xotcl] Some fixes to xodoc

From: Kristoffer Lawson <setok_at_fishpool.com>
Date: Thu, 21 Dec 2000 03:11:44 +0200 (EET)

Attached to this post I have a slightly fixed version of xodoc. I did the
following corrections/additions:

- Added space between the different "sections" of class
descriptions. Ie. as in the following case:

_at_ Class Foo {
  description {blah}
  errors {foo}
}

It would just stick 'description' and 'errors' on to the same line.


- Added functionality to handle optional procedure arguments. Ie. as in
thee following case:

_at_ Foo instproc {arg1 {arg2 ""}} {}

Now it marks arg2 as optional with the standard Tcl syntax, and also
automatically specifies the default value along with the description.


- Added some special handling for the section 'errorCodes' in a
class. These error codes are the things you can give with the
[error] command to give a code to the error, so catching is
easier. Ie. the following:

_at_ Class Foo {
  description {blah}
  errorCodes {
    MyAppError {
      Used for sending errors my application specifically
      creates.
    }
  }
}


What I didn't do:

I was going to add an extension facility so that applications could
specify their own handler-objects for certain special sections. Like in
Class Foo above I might have a section {Attribute Aliases} in addition to
errorCodes (as I do). I would like to specify a AttrAliasDocHandle object,
for example, which would have the method "toHtml" (if outputting HTML)
that gets called when the section {Attribute Aliases} is encountered, with
the data passed to it as an argument. This would then return a nice HTML
table documenting my aliases.

The syntax to create an extension might be something like this:

_at_ @DocExtension Class {Attribute Aliases} AttrAliasDocHandle

I would have done this myself but it's already late (3am) and I really
desperately need to continue my real work. If anyone feels like
implementing that, then feel free... Otherwise I'll just have to get back
to it at some later time :-(

         - ---------- = = ---------//--+
         | / Kristoffer Lawson | www.fishpool.fi|.com
         +-> | setok_at_fishpool.com | - - --+------
             |-- Fishpool Creations Ltd - / |
             +-------- = - - - = --------- /~setok/