Since it still looks as though we are going to have our own
documentation generator, I want to fix a problem with Sun's JavaDoc
and introduce a few new tags. Assuming no one objects, I'll go ahead
and add this to the hacker's guide.
JLS 18.3 - Summary Sentence and General Description.
This is stupid. If I want to credit Prof. Knuth in the summary
sentence, I should be able to. The obvious solution is to do what
Emacs does to recognize end of sentences.
In order to be recognized as the end of a sentence, the ending
period, question mark, or exclamation point must be followed by
two spaces, unless it's inside some sort of quotes or parenthesis.
We'll just match the regex of:
"[.?!][]\"')}]*\\($\\| $\\|\t\\| \\)[ \t\n]*".
New tags
1) @JLS [0-9]+(.[0-9]+)*(-[0-9]+C?)?
The JLS tag creates a link to the Java Language Specification. The
section must be specified, but subsection, subsubsection, etc. are
optional. The "-[0-9]+" is used to indicate, if necessary, the
edition (1st edition is assumed). A `C' is tacked on if the
implementation is based on a correction to the specified JLS
(ie. Appendix D for the 1st edition of the JLS).
2) @XXX paragraph
A marker that attention is needed. Commonly used in program comments
to indicate areas that are kluged up or need to be.
3) @FIXME paragraph
A marker used near a piece of code that needs work.
--
Paul Fisher * [EMAIL PROTECTED]
