4

I would like to generate javadoc for my classes. The 'generate Javadoc' command gives me an option to create Javadoc for members with visibility Private/Package/Protected/Public. But there are some public methods I don't want to be included in the Javadoc. How can I specify for this Javadoc generator exactly which members/methods to include and which ones to not include?

(I use eclipse 3.4.2)

Edit: Some of you asked what is the reason I want to do this. The reason is that I have some methods which I don't want to exist but I still need them to work for backward compatibility. I marked them as @deprecated so that people who try to use them will recieve a warning. But I don't want them to appear at all in the Javadoc. Is there a way to exclude them from the javadoc given they're marked @deprecated?

wattostudios
  • 8,666
  • 13
  • 43
  • 57
snakile
  • 52,936
  • 62
  • 169
  • 241
  • 5
    Any particular reason why you want to do this? If you wanted to "hide" a public method, it would suggest to me that your implementation is broken. See here: http://stackoverflow.com/questions/1928467/annotation-to-disable-javadocs – JasCav Jan 18 '10 at 19:09
  • I agree with Jason... public is public. – cjstehno Jan 18 '10 at 19:15
  • You cannot hide from the public what's for the public :) – Mihir Mathuria Jan 18 '10 at 19:45
  • Thanks all. I agree that "public is public". But the methods I would like to exclude are deprecated. The only reason I don't delete them is for backward compatibility. I edited the question to mention this. – snakile Jan 18 '10 at 20:15
  • 2
    I would argue that deprecated methods are the ones that need documenting the most, so that you can tell people to stop using them and use whatever-new-method instead! – matt b Jan 18 '10 at 20:21
  • @Matt: I don't disagree, but I have certainly had deprecated methods in the past that I just wanted to hide all trace of because their documentation clutters up an otherwise clean API; esp. when they are deprecated early in the API life-cycle before many customers have seen them. – Lawrence Dol Jan 19 '10 at 03:47
  • The problem with this approach is that when it comes to Java classes, you can't really hide what methods exist/don't exist – matt b Jan 19 '10 at 15:21

4 Answers4

3

So, why does javadoc -nodeprecated not do the trick?

atk
  • 9,244
  • 3
  • 32
  • 32
  • 1
    Looks like this is the right way to go to me. It seems to be a bug in javadoc though that the java @Deprecated annotation does not cause the method to be excluded, you must use the @deprecated tag in the javadoc for the method. – Geoff Reedy Jan 18 '10 at 20:41
  • I think this is my answer. I'm not around my computer so I'll check it tomorrow and probably accept you answer. Thanks. – snakile Jan 18 '10 at 20:50
  • +1: When I answered he had not said why he wanted to exclude the methods, or I would have suggested the same thing. – Lawrence Dol Jan 19 '10 at 03:45
1

You would have to write your own Doclet.

Lawrence Dol
  • 63,018
  • 25
  • 139
  • 189
0

So you have some methods that must be public for some reason, but are something that class users should not really mess with?

You could put this kind of JavaDoc for those "hidden" public methods:

 /**
  * !!! THIS METHOD IS NOT PART OF PUBLIC INTERFACE !!!
  * !!! DO NOT USE !!!
  */
 public void somethingThatShouldNotBeUsedByOutsiders()

I took a quick glance and there seems to be no way to do method level exclusions at least via the standard JavaDoc tools.

Juha Syrjälä
  • 33,425
  • 31
  • 131
  • 183
  • This reminds me of a DailyWTF entry http://forums.thedailywtf.com/forums/p/3616/88501.aspx Users will NOT listen when the documentation warns them not to use something. It's sad but true. – Chris Nava Jan 18 '10 at 22:02
0

As Software Monkey wrote, you probably have to write your own Doclet. There's an example which does nearly what you wanted, the ExcludeDoclet

mhaller
  • 14,122
  • 1
  • 42
  • 61
  • Thanks. But what I want is to exclude methods, not classes. I think this tool only enables excluding classes. Any other idea? – snakile Jan 18 '10 at 20:21
  • 1
    Download and change it. It's an example (click the example link). Else, try http://developer.berlios.de/projects/padoclet/ – mhaller Jan 18 '10 at 20:24