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

[Scott Marlow]

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
>>> _______________________________________________
>>> jboss-development mailing list
>>> jboss-development at lists.jboss.org
>>> https://lists.jboss.org/mailman/listinfo/jboss-development
>>
>> _______________________________________________
>> jboss-development mailing list
>> jboss-development at lists.jboss.org
>> https://lists.jboss.org/mailman/listinfo/jboss-development
> _______________________________________________
> jboss-development mailing list
> jboss-development at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-development