Win a copy of JDBC Workbook this week in the JDBC and Relational Databases forum
or A Day in Code in the A Day in Code forum!
  • 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
  • Paul Clapham
  • Jeanne Boyarsky
  • Junilu Lacar
  • Henry Wong
Sheriffs:
  • Ron McLeod
  • Devaka Cooray
  • Tim Cooke
Saloon Keepers:
  • Tim Moores
  • Stephan van Hulst
  • Frits Walraven
  • Tim Holloway
  • Carey Brown
Bartenders:
  • Piet Souris
  • salvin francis
  • fred rosenberger

Question about generating Javadoc

 
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.
 
Sheriff
Posts: 11604
178
Hibernate jQuery Eclipse IDE Spring MySQL Database AngularJS Tomcat Server Chrome Java
  • 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.
 
She's out of the country right now, toppling an unauthorized dictatorship. Please leave a message with this tiny ad:
Devious Experiments for a Truly Passive Greenhouse!
https://www.kickstarter.com/projects/paulwheaton/greenhouse-1
    Bookmark Topic Watch Topic
  • New Topic