Win a copy of The Little Book of Impediments (e-book only) this week in the Agile and Other Processes forum!
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic

copy javadoc when using decorator/wrapper pattern ?

 
Ronald Wouters
Ranch Hand
Posts: 190
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi all,

I have a class called ConcurrentData which is simply a Decorator/Wrapper around my Data class. ConcurrentData wraps each method of Data with eiter a ReadLock or a WriteLock and then delegates to the corresponding method of Data itself.
My question is what should you do, in general, with the Javadoc when using this kind of "wrapping/decorating" ? I can't use the @inheritDoc tag because that doesn't work in this case. Should I copy the complete Javadoc from Data to ConcurrentData ? Or, perhaps use a simple @see tag in ConcurrentData to reference the corresponding method in Data ? I have found nothing on this on the Javadoc website.

Regards,
Ronald Wouters
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12012
216
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ronald,

In this case I would probably duplicate the Javadoc comments in your adapter / decorator class. This would allow for the possibility that someone might modify the Data class at some point in the future while not changing your adaptor / decorator - in such a case you want the comments to reflect what the adaptor / decorator is really doing.

Regards, Andrew
 
Ronald Wouters
Ranch Hand
Posts: 190
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Andrew, thanks for your insight.
If you will allow it, I will mention this in my choices.txt.
Or is something like this too insignificant to mention ?

Regards,
Ronald Wouters
 
Andrew Monkhouse
author and jackaroo
Marshal Commander
Pie
Posts: 12012
216
C++ Firefox Browser IntelliJ IDE Java Mac Oracle
  • Mark post as helpful
  • send pies
  • Quote
  • Report post to moderator
Hi Ronald,

There is no reason for asking if I will allow something or not.

Regards, Andrew
 
  • Post Reply
  • Bookmark Topic Watch Topic
  • New Topic