• 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 Pie Elite all forums
this forum made possible by our volunteer staff, including ...
Marshals:
  • Campbell Ritchie
  • Jeanne Boyarsky
  • Ron McLeod
  • Paul Clapham
  • Liutauras Vilda
Sheriffs:
  • paul wheaton
  • Rob Spoor
  • Devaka Cooray
Saloon Keepers:
  • Stephan van Hulst
  • Tim Holloway
  • Carey Brown
  • Frits Walraven
  • Tim Moores
Bartenders:
  • Mikalai Zaikin

Question about generating Javadoc

 
Ranch Hand
Posts: 160
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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.
 
Sheriff
Posts: 11604
178
Hibernate jQuery Eclipse IDE Spring MySQL Database AngularJS Tomcat Server Chrome Java
  • Mark post as helpful
  • send pies
    Number of slices to send:
    Optional 'thank-you' note:
  • 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
    Number of slices to send:
    Optional 'thank-you' note:
  • Quote
  • Report post to moderator
Cheers, thanks for your kind response and answering both parts of the question.
 
My honeysuckle is blooming this year! Now to fertilize this tiny ad:
a bit of art, as a gift, that will fit in a stocking
https://gardener-gift.com
reply
    Bookmark Topic Watch Topic
  • New Topic