[JSR308] Replace JAIF format with XML for external annotations

[David Hovemeyer]

On 8/22/07, Michael Ernst <mernst at csail.mit.edu> wrote:
> The tools, including the parser, are available at
>   http://groups.csail.mit.edu/pag/jsr308/annotation-file-utilities/
> It looks like we made the first public release on 1-May-2007.

FWIW, here's my $.02.

I've worked a bit with both the tools and the annotation
file spec.  There are a number of issues that prevent either
from being directly usable for my purposes in their
current state.

Here are a few of my concerns, off the top of my head:

1. No source code for the annotation file parser

2. No API docs for the annotation file parser

3. The implementation does not specify a license

4. The grammar in the annotation file spec is inconsistent
  and incompletely specified
   [I've emailed a couple of my concerns to the javari mailing list]

5. The annotation file spec refers back to the JLS in a couple
  places, for example, constant values.  This means that
  just tokenizing an annotation file is not a trivial task.
  Do I need to handle unicode escapes?  Octal constants?
  Hexidecimal floating-point constants?
    [I'm making the assumption here that the annotation file
   spec is intended to be a token-based format, but that's
   actually not at all clear in the current version of the spec.]

If concerns (1) - (3) are addressed, I might be able to
just use the current implementation as a library.
(I'm not thrilled with the idea of the implementation being
a de facto specification, of course.)

Concerns (4) and (5) worry me a lot more.  Even assuming the
spec were nailed down precisely (lexical and grammar level),
I'm still looking at a significant chunk of work to implement it,
probably using a parser generator.

Returning to Bill's original suggestion, an XML schema
or DTD would address of all of these concerns.
I know readability has been mentioned as a concern.
Personally, I find XML to be "readable enough", and while
writing it by hand is a bit tedious, I don't think it's any
more difficult than learning the intricacies of a new file format.
(To be honest, I think it would be *easier* to
learn than a custom file format, since the lexical and
grammatical structure are completely obvious in XML.)

-Dave