How do I exclude a specific method/constructor from the results of the javadoc Ant task?

Question

I'm using javadocs generated by the javadoc Ant task to document a web service, and I want to exclude some constructors from the output. How do I do that?

Answer 1

There is no way to do this for public methods. The standard practice (even in quite a few JDK classes) is to indicate that the method or constructor is not meant for public use.

There is a plan to add an @exclude tag in the future:

@exclude - for API to be excluded from generation by Javadoc. Programmer would mark a class, interface, constructor, method or field with @exclude. Presence of tag would cause API to be excluded from the generated documentation. Text following tag could explain reason for exclusion, but would be ignored by Javadoc. (Formerly proposed as @hide, but the term "hide" is more appropriate for run-time dynamic show/hide capability.) For more discussion, see: Feature Request #4058216 in Developer Connection.

Answer 2

Isn't excluding something public from your documentation just a variation on "security through obscurity" (or rather, "documentation through obscurity")? If the constructor is part of your code's API, it's available for them to use. If they find out about it and use it, is that their fault (since you made it public in the first place)?

If you can change the constructor's visibility or remove it altogether, I would go for that. If you cannot remove it from the API, make it known in the Javadoc for the constructor that it's not intended for use via web service. That way you've established a contract with users of your API, informing them not to use it.

It's better to document that it should not be used instead of not documenting it at all (if it's public). Not documenting it adds risk that it gets inadvertently used, and then the client code using it breaks when you change the implementation.