Annotation to disable JavaDocs

Question

Is there an annotation to declare that a certain method will not be included in the JavaDocs even though it is public?

Something like:

@nojavadocs
public void foo(){
//...
}

---

P.S. I understand the point here about API, but the methods are simply "unsupported." They work (and must be public for access from other packages), but we do not want to bother documenting them and answering questions about how to use them when their functionality is not relevant to supported usage scenarios. Good design might mean moving them to another class, but they logically refer to the data in the class.

Exterritorial

Answer 1

Not if you're using Sun's JavaDocs tool.

They have a feature request for it, but it's been in low priority since 1997.

You can write a custom doclet to overcome this, or use a 3rd-party tool (DocFlex or such).

Methadone

Good to hear there's a feature request -- at least I'm not the only dummy asking for this :-) – Exterritorial

Answer 2

The only reason I could think of that you'd want to do this would be to "hide" the method in some sense, if only in terms of documentation. If you did that you'd be designing the documentation to be "broken" in the sense that documentation becomes broken when it goes out of date and no longer accurately reflects what the class does. Since the method is still part of the public API you're not really hiding it anyway.

If you want a method to be unused outside of the class or a few users, make it private, or package. If this is inconvenient and it must be public, I'd just document very clearly the limitations on its use, possibly with a naming convention (for example, python does this, there are entity names surrounded by underscores, that you can see but are meant to be more part of the class implementation than the public api)

Kass

Answer 3

Yes...but not in a good way (having methods that are public that aren't really "public" isn't a great design practice).

You could follow the suggestion given in this thread and mark the method using @deprecated then when you run javadoc use option -nodeprecated.

Edit: As others have noted, this is not a desirable course of action. This will solve your problem, but you really need to rethink why it is you want to hide the method -- given a compiled version of your code someone will still be able to see your function; hiding it in the documentation does not in fact hide the method. I really mean to stress here that the qualifiers private, public and protected have meaning which you should consider and utilize effectively. There is no such thing as a "hidden" public method.

Bivens

This will work, and is a clever solution, but it's a problem in that you're misusing the deprecation annotation, so you're code doesn't match what it "means". At the very least I'd comment the methods and clearly explain why I was doing something this odd. Tools (e.g. eclipse) will flag a warning for use of deprecated methods (although you could mark those warnings to be ignored). – Kass

I'm not advocating the use of this tactic -- clearly there's a larger issue here and the effects of marking something @deprecated can be extremely undesirable, but it satisfies the OP's needs. The thread I linked to on the Java forums suggests exactly as you do that the method should be clearly commented to avoid confusion. – Bivens

Answer 4

/**
 *  Don't use this method <br>
 *  <i>or all your data will be lost.</i>
 */
public void foo(){
    //...
}

well, use a better explanation why the user should not use this method...
Remember that it's not hard to find any (public) method using a decompiler or Reflection.

Vive

Answer 5

You can use a comment

    /*
     * (non-Javadoc)
     * 
     * @see DescriptionSupplier
     */

to ignore such methods.

Coaming

Answer 6

I actually did something similar to this in a project i own called Jackcess. The API contains methods of varying degrees of complexity, and I wanted an easy way of indicating that in the javadoc. I pieced together some functionality that seems to work reasonably well using some comment conventions and a maven plugin.

In the code, I have a simple pattern i use in the javadoc (example from here):

  /**
   * @return the current database password, or {@code null} if none set.
   * @usage _general_method_
   */
  public String getDatabasePassword() throws IOException;

You can use "general", "intermediate", or "advanced" combined with "class", "method" or "field".

A pom plugin replaces that with the relevant javadoc using the replacer plugin after building the javadoc, example here.

The end result looks like this or this. (I have some custom css added to the javadoc to add the coloring).

---

---

---

Dialectology