[antlr-interest] ANTLR Javadocs

[David-Sarah Hopwood]

Gavin Lambert wrote:
> At 07:31 26/08/2009, David-Sarah Hopwood wrote:
>>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.
> 
> For that to be correct, though, you'd have to link to a specific version
> of the docs.  (ie. the site would have to have different URLs for the
> 3.1.0 docs vs. the 3.1.1 docs, etc).

Even just the latest version would be useful, but yes, different URLs for
each version (and one for the latest) would be better. Once you have it
set up, it's really very little work per release.

In any case, my view is that it's always the responsibility of the
reader of documentation to make sure they are looking at the right
version. The convention for javadocs is to display the version prominently
at the top-right of every page.

> Seems simpler just to include them yourself, if you need to.

Not a chance. The problem isn't really the size of the generated docs;
it's the dependency on the ANTLR source distribution to build them.
Currently that is 10.2 MB gzipped, or 19 MB un-gzipped (23.4 MB on disk
for an NTFS filesystem, which stores small files wastefully).

Adding this huge and not-otherwise-needed dependency (for my current
project it would be over 200 times larger than my own code), especially
in the case of an open source project where you want users to be able to
build docs from source themselves, would be completely prohibitive.
There's just no comparison between that, and adding one line that says
something like '-link "http://www.antlr.org/api/3.1.3/javadoc/"' to a
javadoc options file.

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