[jboss-dev] building the documentation for JBoss public and private API...

[David M. Lloyd]

On 06/01/2009 03:19 PM, Scott Marlow wrote:
> We were just talking about building a list of all JBoss AS public API 
> calls.  This will be used to document the public API versus what is 
> considered private (we will include only the public API in this "public 
> api" documentation).
> 
> One idea mentioned already is that we could use an annotation (e.g. 
> something like @publicAPI mentioned elsewhere 
> http://www.opends.org/promoted-builds/2.0.0-RC1/javadoc/org/opends/server/types/PublicAPI.html).  
> We would then build the "public API" documentation based on the 
> @publicAPI annotations (the how to be determined).
> We might want to also include a @privateAPI tag, for source files that 
> contain a mix of public and private API (or maybe we should move 
> anything private into separate modules).

The way I traditionally tackle this is by using package-private access for 
non-API stuff in the API package.  Otherwise, a taglet would be a great way 
to do this (annotations are probably overkill).  Javadoc may be an old 
technology but it's still decent.

One thing I also have for Remoting 3 is a set of javadoc tags that I can 
stick on a class or interface which causes a generic explanation to be 
appended to the javadoc (like "This interface is intended to be implemented 
by the end user" or "This interface is intended for service providers, so 
new methods may be added without notice", etc).  I can provide a link as 
soon as I get around to getting the javadoc published for 3.1.

- DML