如何从javadoc Ant任务的结果中排除特定的方法/构造函数？

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

See the relevant Javadoc FAQ entry .

There is currently no Javadoc option to hide, exclude or suppress public members from the javadoc-generated documentation.

It would appear this is not possible in the vanilla Javadoc, but some workarounds are offered.

Answer 3

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.

Answer 4

Change the method access level of the method, then use the use the javadoc task's access-level filtering attributes, private , package , etc. Only do this if it makes sense in your code, though, eg, method that had inappropriately loose access levels.

For constructors, for example, you could reduce the access level to package , then create a factory class in the same package that provides construction access outside the package. The factory class can be easily filtered from the javadocs. Kind of hacky, but it works.

Answer 5

Give Chris Nokleberg's ExcludeDoclet a try: http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html

I've just been experimenting with it and it seems to do the trick.

Answer 6

Currently the simplest solution is to start the javadoc comment with @deprecated , and then pass -nodeprecated to the javadoc command. Of course, this may not be acceptable if you have actual deprecated items which you nevertheless want to include in the documentation.

Answer 7

我得到的结果是使用Doclava ，它具有@hide标记，您可以在方法文档中指定该标记。