I have some generic methods in a class of mine, for instance
Now, when generating javadoc, I get errors like "element not closed: S. If, however, I leave out the "<>", I get the error that "@param name not found", and the generated javadoc has all letters in strike-through..
I'm certainly no expert when it comes to html, but how can I handle this?
I think the "@param <S>", "@param <T>" parts are all fine. The javadoc parser understands you're referring to the parameter names S, T, etc, if only because it's immediately after the @param tag and it's looking specifically for a parameter name there.
The problem is later when you refer to "Collection<S>". It doesn't know what <S> is, and tries unsuccessfully to interpret it as a tag.
You can instead replace some of the < with < , so that "Collection<S>"" becomes "Collection<S>"
All of this renders javadoc annoyingly difficult to read when you're looking at the source code, if you're actually using it as HTML and paying attention to how it will be rendered. Which is an annoying feature of javadoc in general as it's been implemented; nothing new there.
Also, I had to put quite a few < in this post. As well as some &lt;, and even some &amp;lt;. And more, but best if I stop there. ;)
And I deleted all references to "u" because the forum software doesn't like that letter by itself. Sigh.
posted 2 weeks ago
thanks for your reply (via the Purple Moosage!). Your solution worked, but makes reading as you said somewhat more difficult!
But I just foud out that if I write this
generates beautiful javadoc, but I never like "?" in genereic parameter types, find them hard to read. The javadoc tool produces the poetic:
Edit: and thanks for your regular reply as well! And I have the same as you: I often use 'r' in some replies, but that Censor.....
posted 2 weeks ago
You're welcome, Piet. I would also say that I usually wouldn't bother restating any info about the type of those params anyway - that info is already clearly specified in the declarations of those params, and will be picked up as part of the javadoc. Why restate it and (a) make the comment longer, and (b) add new opportunities for errors? I routinely delete everything in a javadoc that is just a restatement of what the signature already says.
Your example of using a List.of(List) is the most useful part of the comment anyway, since it summarizes the combined effect of the generic params. So, focusing on that example and dropping the rest sounds good to me.
Piet Souris wrote:Beware: you can use a Set, but then the order of the elements might be completely different than as specified in the Set! There's no ordering in a Set...
Good call. Except... why allow Sets here at all? Why not just require a List?
Mike Simmons wrote:(...)Good call. Except... why allow Sets here at all? Why not just require a List?
Blame Stephan! He's the one who made me make these things more general than what I always did. But when testing, a Set was useless indeed. It took me some time to figure out why my JUnit test
assertTrue(Matrix.of(Set.of(1, 2, 3)).equals(Matrix.of(1, 3, 1, 2, 3) (creates a 1x3 matrix)) failed... that's why I put a warning in my doc.
Yes, use Collection in your factory method, because even sets may have a well defined encounter order. People who use LinkedHashSet will thank you, as well as people who use other ordered collections that don't implement List, such as ArrayDeque.
Don't use generic type parameters when you don't need them. When do you need a generic type parameter? It's either when the return type depends on the type of an argument, or when the generic type of one method parameter must relate to the generic type of the current instance, or that of another parameter.
There's no point in creating type parameters for the collections. You only care that they're collections. The only interesting type information that you want from the user is the type of the matrix elements.
posted 2 weeks ago
Generic matrices? Beware of generic headaches then.