• Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

Question about generating Javadoc

 
Mark O' Sullivan
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi, just wondering when writing Javadoc for param tags of say methods, can one use the <code> </code> syntax. Just wondering because:
(1) When describing params of methods, is one suppose to use natural english instead of refering to existing structures in code, for example, if referring to a deletedRecordsCache in the param tag, should one use natural English, for example, use deleted records cache, or enclose the structure withing <code>deletedRecordsCache</code>.
(2) I realise if using the <code></code> tags this could raise a problem, say using the same description for interface methods and the class that implements them, seeing the interface class may not have the appropriate data structures.
Thanks very much.
 
Roel De Nijs
Sheriff
Posts: 10662
144
AngularJS Chrome Eclipse IDE Hibernate Java jQuery MySQL Database Spring Tomcat Server
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Mark,

Of course you could use the code-tags. If you are commenting your interface you can of course not add comments about implementation details, because an interface is a contract about what an implementation has to do, not how it has to be done.

I used the code-tags to indicate null, true, false and also to refer to a method parameter. Example (only appropriate comments are shown):


Kind regards,
Roel
 
Mark O' Sullivan
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Cheers, thanks for your kind response and answering both parts of the question.
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic