javadoc 从类中排除一些公共方法 [英] javadoc exclude some public methods from class

问题描述

我必须将类的一些公共方法排除在 javadoc 中.我尝试了 Chris Nokleberg 的 ExcludeDoclet (sixlegs).但是 doclet 给出了一个小问题:如果类中的其他方法返回 List(或任何其他泛型)，而不是在 javadoc 中显示为 List，返回类型只是显示为 List(没有通用信息)

I have to exclude a few of the public methods of a class from being included in javadocs. I tried Chris Nokleberg's ExcludeDoclet (sixlegs). But the doclet is giving a slight problem : If the other methods in the class return List (or any other generics), instead of being displayed in the javadoc as List, return type is just being displayed as List (without the generic info)

任何人都可以就如何解决这个问题给出提示或提供解决方法吗?

Can anyone give a hint or provide a work around on how to solve this issue?

推荐答案

我假设您要从 javadoc 中排除的方法是您不希望客户端使用的公共方法.换句话说，这些方法已弃用.您需要做的是使用@Deprecated 注释.像这样:

I assume the methods you want to exclude from javadoc are public methods that you don't want your client to use. In other words, these methods are deprecated. What you need to do is using the @Deprecated annotation. Like this:

@Deprecated public void badMethod() {
    ...
}

现在，badMethod() 已被弃用.如果有人在他的代码中使用了 badMethod()，他会收到来自编译器的警告(他使用的是不推荐使用的方法).

Now, the badMethod() is deprecated. If someone uses badMethod() in his code, he'll get a warning from the compiler (that he's using a deprecated method).

但是，@Deprecated 注释不排除 javadoc 中已弃用的方法.为了从 javadoc 中排除该方法，您需要执行以下操作:生成 javadoc 时，请使用 nodeprecated javadoc cmd 行选项.-nodeprecated 选项可防止在文档中生成任何已弃用的 API.因此，如果您使用 @Deprecated 批注并使用 -nodeprecated 选项生成 javadoc，那么您的错误方法将不会出现在 javadoc 中.

However, the @Deprecated annotation doesn't exclude the deprecated method from javadoc. Here's what you need to do in order to exclude the method from javadoc: When you generate javadoc, use the nodeprecated javadoc cmd line option. The -nodeprecated option prevents the generation of any deprecated API in the documentation. So if you use the @Deprecated annotation and generate javadoc with the -nodeprecated option, your bad method won't appear in the javadoc.

但在我看来，您不应该从您的 javadoc 中排除已弃用的公共方法.如果它们出现在文档中并解释为什么不推荐使用该方法以及使用什么来代替，那就更好了.

But in my opinion, you shouldn't exclude deprecated public methods from your javadoc. It's better if they appear in the documentation with an explanation of why the method is deprecated and what to use instead.

这篇关于javadoc 从类中排除一些公共方法的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！