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 List: http://www.antlr.org/mailman/listinfo/antlr-interest Unsubscribe: http://www.antlr.org/mailman/options/antlr-interest/your-email-address --~--~---------~--~----~------------~-------~--~----~ You received this message because you are subscribed to the Google Groups "il-antlr-interest" group. To post to this group, send email to [email protected] To unsubscribe from this group, send email to [email protected] For more options, visit this group at http://groups.google.com/group/il-antlr-interest?hl=en -~----------~----~----~----~------~----~------~--~---
