[antlr-interest] ANTLR Javadocs

[David-Sarah Hopwood]

Terence Parr wrote:
> On Aug 25, 2009, at 2:19 PM, Sam Barnett-Cormack wrote:
>> David-Sarah Hopwood wrote:
>>> Terence Parr wrote:
>>>> hi. not sure what's wrong with the doxygen..can you be more specific?
>>>
>>> Suppose someone wants their javadoc implementation to include links
>>> into ANTLR classes. They could run javadoc on the full ANTLR source,
>>> or they could just use the "-link <url>" option of javadoc to point
>>> to somewhere on the ANTLR site. The latter is much easier, and doesn't
>>> require them to ship the ANTLR documentation with their own
>>> documentation.
>>
>> Specifically, it has to be javadoc because of the specific directoy
>> structures and suchlike used by javadoc, including a specific file I
>> forget the name of, that it uses to figure out which classes are under
>> which URL.

(The name is "package-list".)

> thanks everyone. I see the issue now. Yes, ANTLR should have a standard
> documentation but unfortunately we have doxygen at the moment. since it
> is just Java, though, can I just run Java doc on everything and put it
> at a standard place on the website?

Yes. As far as I know there are no special options to javadoc needed to
produce output that can be linked to.

The following javadoc options are helpful, though:

  -linksource -sourcetab 4
    Link method and class names to an HTML version of the source code
    with line numbers, similar to the current doxygen ANTLR docs
    (not as pretty, but never mind).

  -link "http://java.sun.com/javase/6/docs/api/"
    Link names of Java API classes to Sun's docs. (The assumption of
    JavaSE 6 is good enough.)

  -header "<b>ANTLR API<br>Version ...</b>"
    Add a version header in a style consistent with Sun's docs.

I would put the options in a text file and use @<filename> on the
javadoc command line; that's easier to maintain, avoids command
length limits on some platforms, and allows you to control the set
of documented source files (e.g. excluding generated files) more
easily.

> It would have to include a version number as you say.

See the -header option above.

-- 
David-Sarah Hopwood  ⚥  http://davidsarah.livejournal.com