Ever since I got bitten by the Scheme bug, I've been trying out different styles of documentation within the comments of the code. Currently I use block style comments #| .. comment .. |#, within which I place XML code. A typical source file of mine starts off like this:
#| <header> <name>source.scm</name> <author>Kyle Smith</author> <created date="2006-11-13"/> <description> Source.scm is designed ... </description> </header> |#
The advantage to this is that I can save my source.scm to source.xml, and use standard XML tools to process the document. The downside is that once I've got myself into a thousand line source file, heavily documented with XML, there are countless cases where I've forgotten to close an element, made a typo on one of the elements or forgotten the slash in the closing element. All this adds up to a very long boring session with Stylus Studio, correcting my silly mistakes.
So, I went in search of a new way to do things. What I've come up with I call Active Comments, because they don't reside inside Scheme comments, they are live Scheme code. Because they are active code, and because most of my comments occur around the definitions of functions and syntax, they have been designed such that their expansion does not break definition context. They have some similarity to sxml, except that there is no @ sign before attributes. There is, however, an @ sign that introduces an Active Comment. They look like this:
(@ function) (@ name fact) (@ author Kyle Smith) (@ created ((date "2006-11-13"))) (@ description compute factorial of number? -> n) (@code (define fact (lambda (n) (or (and (= n 0) 1) (* n (fact (- n 1)))))) )
Most Active Comments are simply expanded to:
(begin (define name (lambda () '(e1 e2 ...))))
Since the element @code actually encloses a definition it is defined as:
(define-syntax @code (syntax-rules () ((_ ((i1 v1) ...) e1 e2 ...) (begin (define 'i1 'v1) ... e1 e2 ...))))
What do I get for all this trouble? The formatting of the date attribute is enforced by the syntax from which the created element is defined. All the element names must be spelled correctly. Closing a comment is just a matter of balancing parentheses. All of these things happen each time I write a comment, by the native Scheme syntax checker.
Well, that's just the start of the story. In my next post I discuss my efforts to design syntax for Active Comments that allows them to be arbitrarily nested within other Active Comments. Let me just say that it can be done, but it comes at a price.--kyle