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

[Anil Saldhana]

If you look at the Java EE javadoc bundle for example - there is no 
clear separation between what is applicable to SPI implementers, 
container vendors and JavaEE users.

We really need documentation on API that is for public usage ( both 
users as well as JBoss system integrators) and of course the private api.

Scott Marlow wrote:
> One illegal usage might be detecting that a private (JBoss internal) 
> API was used by a customer application.  This would be useful for our 
> customers to know as private API can change unexpectedly from release 
> to release.
>
> Applications that use private APIs will need more refactoring during 
> migration to a new AS release.
>
> Perhaps we could also have a usage check for unsupported APIs (some 
> projects have contributions that may be considered experimental).
> David M. Lloyd wrote:
>> Illegal usages such as what?
>>
>> - DML
>>
>> On 06/01/2009 04:04 PM, Emmanuel Bernard wrote:
>>> +1 for annotations as we could also flag illegal usages at compile 
>>> time via an annotations compiler.
>>>
>>> On  Jun 1, 2009, at 17:00, 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.
>>>>
>>>> - DML