This is the mail archive of the kawa@sourceware.org mailing list for the Kawa project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: annotations for Kawa


On 12/04/2010 09:00 PM, Jamison Hope wrote:
It's valid to have multiple annotations attached to a single declaration
in Java,
so Kawa should handle multiple annotations as well:

[v2a] (define var (@Deprecated) (@Foo) ::type init-expr)
[v2b] (define var ((@Deprecated) (@Foo)) ::type init-expr)

Either of these would work for me.

[v2a] is what I had in mind. [v2b] complicates the syntax needlessly.


I've mentioned before that I think a @Documentation annotation would be
a good way
to store Lisp-style documentation strings so that they would still be
available at
runtime. At the syntax level, then, I would like to see these two forms
as equivalent:

1. (define (square (n ::number))
(@Documentation "Returns the square of the number N.")
::number
(* n n))

2. (define (square (n ::number)) ::number
"Returns the square of the number N."
(* n n))

That is, the compiler should automatically treat as a @Documentation
annotation a
String found as the first expression of the procedure's body (as long as
it isn't
the only expression, in which case the String is not a docstring but
rather the
return value). Presumably the same would go for class methods.

Well, documentation should probably be HTML, not a string:


1. (define (square (n ::number))
     (@Documentation #<p>Returns the square of the number <var>n</>.</>)
     ::number
     (* n n))

2. (define (square (n ::number)) ::number
     #<p>Returns the square of the number <var>n</>.</>
     (* n n))

A documentation "string" might be special case of a documentation HTML,
with an implied <p>.

Working out the details is non-trivial.  One would presumably want to
look closely at JavaDoc's "DTD".

I do have a question about where the annotations will end up in the
class file.

If I write mymath.scm like this:
$ cat mymath.scm
(module-export square)
(define (square (n ::number)) ::number (* n n))

and compile it, javap tells me
Compiled from "mymath.scm"
public class mymath extends gnu.expr.ModuleBody implements
java.lang.Runnable{
public static final gnu.expr.ModuleMethod square;
public static final mymath $instance;
static final gnu.mapping.SimpleSymbol Lit0;
public mymath();
public static gnu.math.Numeric square(gnu.math.Numeric);
public final void run(gnu.mapping.CallContext);
public static {};
public int match1(gnu.expr.ModuleMethod, java.lang.Object,
gnu.mapping.CallContext);
public java.lang.Object apply1(gnu.expr.ModuleMethod, java.lang.Object);
}

so there's a Java method square(gnu.math.Numeric), but there's also a
ModuleMethod square.
Which of these will get the annotations I give to the square procedure
in the source file?

It is not clear what makes most sense, so the plan was to first deal with define-class and its ilk as well as simple variables.

If the Target meta-annotation specifies one of ElementType.FIELD or
ElementgType.METHOD then we should follow that.

Otherwise, I'm not sure whether the annotation should go on the field,
the methods, or both.  Note there may be multiple methods in case of
#!optional parameters.

Most Schemeish would be to put the annotation on the field, since a
function definition is officially just a variable initialized to a lambda.
Plus of course we have the issue of multiple overloaded methods when there
are #!optional parameters. Some annotations might be quite big (for example
Documentation), and emitting multiple copies of the same annotation would be undesirable.


So I think it makes most sense to put the annotation on the field, unless
the Target meta-annotation prohibits that.
--
	--Per Bothner
per@bothner.com   http://per.bothner.com/


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]