This is the mail archive of the
kawa@sourceware.org
mailing list for the Kawa project.
Re: annotations for Kawa
On 12/07/2010 12:37 PM, Jamison Hope wrote:
On Dec 5, 2010, at 1:42 PM, Per Bothner wrote:
Well, documentation should probably be HTML, not a string:
IMHO those are much less readable, especially when viewed in an editor
with syntax highlighting that'll put a simple string in a different
color from surrounding code, but probably doesn't know what to do with
HTML-embedded-in-Scheme (at least I haven't found an appropriate Emacs
mode for that yet).
Clearly, the documentation-as-typed should have some sort of a syntax to
it, but I don't think full-blown HTML is the way to go, for several
reasons:
1. The documentation should be human-readable as present in the source
code,
so that it can take the place of comments. Having SGML tags around
everything stretches that a bit.
To clarify: I think the *stored* representation (as in the class file)
should be xhtml - or at least that should be supported. That doesn't
mean source in the documentation has to be HTML - it could be any expression
or syntax that can evaluate to HTML - as long as it can be evaluated
(constant-folded) at compile-time.
One option I'm toying with is some kind of enhanced "rich-text" literals
with escape sequences. The Scribble system provides some ideas:
http://docs.racket-lang.org/scribble/
However, I don't think I'm ready to make decisions on "rich-text" literals
yet. In the intermediate term, supporting string literals and xml literals
seems OK.
2. When documentation is requested from the REPL (by #'documentation or
#'apropos or #'describe-function or whatever we end up having), tags
will get in the way just like they do in the source code.
That's just a matter of pretty-printing. On a dumb console you could do
the kind of transformation that makeinfo does to produce info file.
Of course there is no good reason (except history) why consoles don't
support multiple fonts, colors, and graphics:
http://per.bothner.com/blog/2007/ReplPane/
3. When being used to generate reference documentation, HTML is only one
of several possibly desirable outputs.
XHTML can be translated into other output formats without much difficulty,
especially if it's a restricted standardized subset of XHTML.
That's why you use TexInfo, right?
Partly. I've considered dropping TexInfo and just using DocBook.
TexInfo has the advantage that it's less verbose, and rather
more readable. However, it's somewhat arcane, and I don't think
it would be a good choice for documentation strings. For one I
don't know of any library that can process "texinfo fragments".
For readability and less of a learning curve, I think the documentation
syntax should be similar to Javadoc or Doxygen, or maybe ELisp docstrings
(which specially interpret `single-quoted-function-names' and
VARS-IN-CAPS).
Javadoc-style or Doxygen-style might be worth considering.
But bottom line: I have a bunch of other things I need to get done
first (including getting annotation actually done ...) before
I want to get too deep into documentation syntax.
For example, we might want to *store* documentation in class files
using XHTML stored in annotations, but the source syntax might be
some form of "doc comments" as in Javadoc or Doxygen.
Interesting. I can do things like
(map java.lang.Math:sqrt (iota 10))
even though there aren't any ModuleMethods in java.lang.Math, so I tend
to think
of the method as the real thing (or possibly a set of methods, in the
case of a
generic procedure or #!optional params) and the ModuleMethod as just an
implementation
detail of the Kawa runtime (just like the gnu.expr.PrimProcedure which
gets created
automatically to represent Math.sqrt or the gnu.expr.GenericProc for
Math.abs).
Yes and no. Making some use of MethodHandles might be reasonable for Java7.
For good or ill, Java7 won't have true function expressions or function
types
(lambdas are mostly syntactic sugar for anonymous classes), so that won't
provide much guidance.
--
--Per Bothner
per@bothner.com http://per.bothner.com/