Using Javadoc with generics

Question

hi, I have not yet found a way to use javadoc on my sources which contain some generics. The tool fails (with errors) and will eventually abort. Is there a doclet or a modified javadoc tool that will work?
error example:
AbstractModel.java:7: '{' expected
abstract public class AbstractModel<M> implements Model<M>

Answer 1

Now it works for me on Netscape, when oddly it didn't
yesterday. Hmmm... I didn't change a thing. Could it have been that you didn't have the "All Classes" frame open? This implementation is sensitive to that. No; you would still have gotten the "not found" dialog.
It seems to be case-sensitive, and require the full
name, which are unexpected, but understandable.Do you think it would be more effective if it were case-insensitive? It's a trivial fix, but since Java is decidedly case-sensitive, I went for that.
Yes, it also requires a correct class name, and not a substring. Not the fulIy-qualified name, though. (That's the whole point; usually I don't remember the fully-qualifed class name.) This can be altered, but you certainly don't want the first substring match to be the class opened.
A big limiting factor is that JavaScript is often really slow. You'll see that if you search for "Applet" it comes up fast because it's early in the list; searching for "ZoneView" takes forever. (You should have seen how slow in older versions of Mozilla.)
If you have to search through the whole list, such as for a "best" substring match, it will tend to always be slow.
I once had a substring search; it gives more trouble than it solves, and leads to more "unexpected" behavior than the current solution. If someone searches for "Link", what should the search show them? There are loads of classes that start with or contain "Link." Maybe just pop up a message box that shows the names of all the possible completions? (I'm not trying to over-engineer this; JavaScript could be made to open new windows, and generate new HTML documents, with select lists, but I'm not sure it's a desirable solution. And "unwanted pop-up blocking" (I love you, Mozilla!) would make none of it work. )
It's ironic that the search field seems to require
the presence of the All Classes list, and yet
somewhat
obsoletes its use (except when wanting to browse
through
names).Well, as you know, JavaScript "introspection" (if you will) requires that the document to be searched is loaded and parsed into a frame on-screen. No real way around that. (I think that using a hidden frame, or popping up a new window, is a horrible idea, so I'm not considering it.) Note that if you have the java.awt classlist open in the lower-left frame, searching for Button WILL work. This may actually be desirable behavior. Note that there are lots of name collisions in Java if you just consider the unqualified class name. If you're working with the AWT, and have the list of AWT classes open in that window, you probably want the AWT List to come up, not the Collection class List.
Maybe, if the class name is not found on the first pass, check the URL of the document loaded in the lower-left frame; then JavaScript can force that frame to reload the "All Classes" window if it's not the one loaded. I wouldn't do it automatically; that behavior may be annoying to users, or it may cause problems like the "List" example above. I'd ask them "Not found in (package x). Do you want to search in all packages?" using a JavaScript confirm() dialog first.
Another benefit and problem that's not obvious: the current solution works on JavaDocs that I've generated, too. You don't want to default to the Java distribution's "All Classes", and you may not even know where the canonical Java docs are to be found, so you can't do the trick listed in the previous paragraph.
Does JavaScript allow it to be modified to overcome
these limitations? Yes, mostly, but with tradeoffs, as discussed above.
Or could it be made to search
through
the index instead, so you could provide a method
before
choosing a class? If the index was on the screen, it could be searched. I'm not sure which class you'd pull up if there were multiple matches.
The current solution isn't meant to be a fix-all searching solution for everything; it's pretty obvious that there are limitations to what JavaScript can and should do. It all depends on what you want to support (including whether you care about browser independence.) This solution is a quick-n-dirty one designed to jump to a known class very quickly without scrolling all through those ever-growing lists, which is all I need 95% of the time. It sounds like you have bigger plans.
The idea of making a little Java Documentation Server that supplies documentation from a compressed file is a better long-term solution, in my opinion. It could do really powerful searches, and be browser-independent (i.e. not requiring JavaScript at all, which is something I don't like about the portability of my solution; I'd rather do everything from within Emacs,) and reduce the space used by Java documentation. I've written such a server in Perl, and I'm very pleased with the space savings, and the fact that it can uncompress and syntax-highlight source files on demand.
I'm hoping that this discussion might save you some time if you decide that this JavaScript-based approach is an approach you want to take for the distribution. Doing this in JavaScript as I've done works, for what I need most, but may not be ideal for the rest of the world.