• Post Reply Bookmark Topic Watch Topic
  • New Topic
programming forums Java Mobile Certification Databases Caching Books Engineering Micro Controllers OS Languages Paradigms IDEs Build Tools Frameworks Application Servers Open Source This Site Careers Other all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Liutauras Vilda
  • Bear Bibeault
  • Tim Cooke
  • Junilu Lacar
Sheriffs:
  • Paul Clapham
  • Devaka Cooray
  • Knute Snortum
Saloon Keepers:
  • Ron McLeod
  • Tim Moores
  • Stephan van Hulst
  • Tim Holloway
  • Frits Walraven
Bartenders:
  • Carey Brown
  • salvin francis
  • Claude Moore

how to handle generic types in javadoc?  RSS feed

 
Master Rancher
Posts: 3189
119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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?
 
Ranch Hand
Posts: 3218
19
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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 &lt; , so that "Collection<S>"" becomes "Collection&lt;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 &lt; in this post.  As well as some &amp;lt;, and even some &amp;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.
 
Piet Souris
Master Rancher
Posts: 3189
119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
hi Mike,

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.....      
 
 
Mike Simmons
Ranch Hand
Posts: 3218
19
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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?
 
Piet Souris
Master Rancher
Posts: 3189
119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Mike,
have a cow for your clear replies!

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.
 
Saloon Keeper
Posts: 10136
214
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
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.
 
Piet Souris
Master Rancher
Posts: 3189
119
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Generic matrices? Beware of generic headaches then.
 
Sheriff
Posts: 21719
102
Chrome Eclipse IDE Java Spring Ubuntu VI Editor Windows
  • Likes 1
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator

Mike Simmons wrote:You can instead replace some of the < with &lt; , so that "Collection<S>"" becomes "Collection&lt;S>"


I think that using {@literal Collection<S>} would also solve the issue.
 
Mike Simmons
Ranch Hand
Posts: 3218
19
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Good call, Rob.  I need to remember that exists.
 
I AM MIGHTY! Especially when I hold this tiny ad:
Create Edit Print & Convert PDF Using Free API with Java
https://coderanch.com/wiki/703735/Create-Convert-PDF-Free-Spire
  • Post Reply Bookmark Topic Watch Topic
  • New Topic
Boost this thread!