Re: Java Annotations?

[Jamison Hope <jrh at theptrgroup dot com>]

On Dec 8, 2009, at 4:08 PM, Per Bothner wrote:

> On 12/08/2009 01:00 PM, I wrote:
> > Is there (or are there any plans for) a facility to annotate  
> > functions
> > or methods in Scheme using Java 5 annotations?
>
> It is not currently supported, and there are no *immediate* plans.
> However, it is on the list of goals, and I have done a little bit of
> thinking about what's involved.  It's not a trivial hack - the
> representation of annotations in class files is pretty complex.
> And then we have to map that into a Scheme syntax.


I've been thinking about that latter part -- mapping annotations into  
Scheme syntax. It strikes me that you already have an applicable syntax:
the optional [keyword: value] pairs used by define-procedure, make- 
procedure, and class field/method declarations. For example:

(define-procedure foo1
  annotation: (@SuppressWarnings "undefined")
  annotation: (@Deprecated)
  (lambda ...))

(define foo2 (make-procedure annotation: ...
                                 method: (lambda ...)))

(define-simple-class junit_tests ()
  ((test1) annotation: (@Test) :: void
   (assert ...)))


[I'm treating the "@" prefix here not as syntax but as a naming  
convention to visually match the analogous Java source. So we'd have  
something like
(define-alias @Test org.junit.Test).]

Although really, since Java annotations can decorate pretty much  
anything (Classes, Constructors, Fields, Methods, …), it should be  
usable anywhere we can currently declare a type. So the keyword  
business should be expanded to work in other places. Which would also  
be handy for writing documentation:

(define (square (x :: number))
  documentation: "Squares the given number.
                  @param x the number
                  @return x^2"
  :: number (* x x)))


(define-alias as org.junit.Assert)
(define (square-junit-test) annotation: (@Test) :: #!void
  (as:assertEquals 9 (square 3))
  (as:assertEquals -1 (square +i)))


The annotation(s) would have to get stored the way the Java spec  
requires (I'll take your word for the difficulty there), but the  
documentation string could just be an ivar of the underlying Java  
object. The real magic with the documentation would be that we could  
have a tool which would produce stub .java files for use with javadoc,  
while also having the documentation available at runtime a la Common  
Lisp docstrings.

/**
 * Squares the given number.
 * @param x the number
 * @return x^2
 */
public static gnu.math.Numeric square(gnu.math.Numeric x);

#|kawa|# (documentation 'square)
"Squares the given number.
 @param x the number
 @return x^2"



That would be super handy, methinks.

-Jamie

--
Jamison Hope
The PTR Group
www.theptrgroup.com