Granny's Programming Pearls
"inside of every large program is a small program struggling to get out"
JavaRanch.com/granny.jsp
  • Post Reply Bookmark Topic Watch Topic
  • New Topic

copy javadoc when using decorator/wrapper pattern ?  RSS feed

 
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
Posts: 12152
256
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
Posts: 12152
256
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
Boost this thread!