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

[David M. Lloyd]

But of course in AS 6, private APIs won't be accessible to customer 
deployments anyway, since we'll have nice API/impl separation and we'll be 
fully modularized.

Right guys?

RIGHT?!?

- DML

On 06/02/2009 09:36 PM, 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
>>>> _______________________________________________
>>>> 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
> 
> _______________________________________________
> jboss-development mailing list
> jboss-development at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-development