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

[Jason T. Greene]

David M. Lloyd wrote:
> 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.

The advantage though of an annotation, is that we can then generate a 
compendium of all public apis for all of our software. You can't do that 
with a note in the javadoc.

-- 
Jason T. Greene
JBoss, a division of Red Hat