1

Frameworks often need to contain classes that have public methods because of the needs of the framework; users using the framework aren't really supposed to invoke them.

For example, a Class might have a public constructor so a factory in another package can instantiate it, but the user is always supposed to use the factory, never the constructor directly.

I'd like JavaDoc to only emit documentation on those methods that a user is supposed to invoke, not others. So in the example, it should document the factory method, but not the public constructor.

Of course, JavaDoc itself won't know which is which, so I was thinking the "public" methods could be annotated with some Annotation, like @SupportedAPI, and JavaDoc would only spit out documentation on those. (This would have the added benefit to mark clearly which methods are expected to remain stable.)

Can JavaDoc be configured to do that?

Johannes Ernst
  • 3,072
  • 3
  • 42
  • 56
  • Why not simply define a clean API by providing interfaces for those methods that should be used by users and document those with JavaDoc? A class implementing this interface will automatically reuse the documentation declared on the interface so no further overhead there – Roman Vottner Jun 01 '15 at 00:31
  • Because not all interfaces are intended to be used by the user, and because there are some classes that are intended to be used by the user (e.g. factories) – Johannes Ernst Jun 01 '15 at 03:45
  • 1
    Then hide those classes not meant to be used by users in a package-hiearchy structure and provide a fassade users can use to interact with your framework. It should not be the job of a framework to hide every detail from users. If (experienced) users want to hook into the inner-details let them do so - if you though insist of hiding the internals at all costs you need to rearange your package- and class-structure. – Roman Vottner Jun 01 '15 at 07:58
  • I was looking for a way to "mark" those classes/interfaces/methods that "normal" users should be using in regular use of the framework for exactly the reasons you mention, and generate two versions of the JavaDoc. But sadly I can't find a way of doing that. – Johannes Ernst Jun 01 '15 at 20:03
  • Also on my wish list and its 4 years later! – Brian Reinhold Jul 10 '19 at 15:12
  • Also on my wish list. This would be an excellent feature from JavaDoc! – Leszek Mar 02 '20 at 11:59

1 Answers1

0

I miss this a lot too. I've got a Java library which is split into packages; some of the methods in it are public only because they need to be used by other package of the library but never by users of the library.

I've been limping along with yDoc - a doclet extension to Javadoc - which adds a @y.exclude tag to classes and methods to prevent them from being documented. That's far from a perfect solution, but still better than the default Javadoc.

Looks like yDoc has been renamed to yWorks. There still seems to be a free Community Edition: https://www.yworks.com/products/ydoc

Leszek
  • 1,181
  • 1
  • 10
  • 21