Distinguishing internal/external methods for Javadoc

问题

I am writing a library in Java. I've divided its implementation into Java packages to help manage the complexity. Only one package contains classes that are visible to clients of the library. However, because only public methods are visible outside of the package for use by other packages of the library, I find myself forced to do one of the following:

(1) Only put interfaces and factory methods in the externally-visible package, putting implementations of those interfaces in a separate package, as described in this SO answer. For example external.MyInterface and internal.MyInterfaceImpl. I find this messy.

(2) Make both internal and external methods public in the external package, and attach Javadoc tags to the internal methods so I can remove their docs prior to publication, either manually (error-prone) or by writing some sort of Javadoc preprocessor or postprocessor.

(3) Use a mechanism that Javadoc provides for this purpose -- ideally, a Javadoc tag.

Whatever the approach, all I really care about is having a consistent way to automatically generate Javadocs for just the external APIs. Is there a standard way to do this? A tool for the purpose?

回答1:

An alternative solution I've been using for years is to add an @exclude tag, using the public domain code provided in this blog: Implementing @exclude using Dynamic Proxies.

To exclude a Java element (attribute, method, constructor, class, inner class or package) from the Javadoc output, just add the @exclude tag in its Javadoc:

public class MyClass {
  /**
   * This is my internal attribute, javadoc not exposed.
   * @exclude
   */
  protected String myInternalAttribute;

  /**
   * This is my external attribute, javadoc is exposed.
   */
  protected String myExternalAttribute;

  /**
   * This is my internal method, javadoc not exposed.
   * @exclude
   */
  public void myInternalMethod() { }

  /**
   * This is my external method, javadoc is exposed.
   */
  public void myExternalMethod() { }
}

回答2:

I found these two answers elsewhere on SO. One approach is to create a custom Javadoc annotation and have an Ant task replace the annotation with deprecated prior to generating the Javadoc. The other, far simpler approach is to use Doxygen's conditional inclusion.

I'm not stuck with Javadoc, so I could go with Doxygen. However, looking at Doxygen right now, it's so different from Javadoc that I'm not sure it's worth the learning curve or establishing a precedent just to be able to generate external APIs.

Here's another solution I will try next time I'm in a position to build: I'll demarcate the portions of the source files that are internal-only, write a tool that duplicates the source files of the external package while removing the portions of the files that are demarcated internal-only, and then run Javadoc off of the generated source. This should work unless Javadoc needs the linker to be happy.

I don't know if it's worth keeping my question around. Might help others find the answer, should they be thinking about it the way I was. Even so, no one has presented a great solution yet.

来源：https://stackoverflow.com/questions/26640222/distinguishing-internal-external-methods-for-javadoc

标签

java

scope

javadoc

libraries