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:
@ 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:
@ 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:
@ 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:
@ @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@fishpool.com | - - --+------ |-- Fishpool Creations Ltd - / | +-------- = - - - = --------- /~setok/
On Thu, 21 Dec 2000, Kristoffer Lawson wrote:
Attached to this post I have a slightly fixed version of xodoc.
great
...
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:
@ @DocExtension Class {Attribute Aliases} AttrAliasDocHandle
Hi Kristoffer,
FYI just a short note in response: I didn't make it to look into the xodoc issues yet (sigh) and probably won't make it this year :) I just want to let you know that we were discussing to extend the basic mechanism, that xodoc+makeDoc use, to a more generic framework for conditional & customized parsing. There are several application which require similar facilities. The extension facility that you propose is one important ingredient.
one general aim is to use the introspection facilities as much as possible without really executing the program (but only parts of it, like namespace in xodoc+makedoc). That way we can build for instance a graphical representation as documentation of a script ... as oppossed to a graphical documentation of a running script. So having such callback handler objects (as you propose for the HTML table representation), would also be important to build such documentation visualizations.
--Uwe
Uwe Zdun Specification of Software Systems, University of Essen Phone: +49 201 81 00 332, Fax: +49 201 81 00 398 zdun@xotcl.org, uwe.zdun@uni-essen.de
-
Kristoffer Lawson -
Uwe Zdun