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

[Emmanuel Bernard]

Naive question, wouldn't it be impractical/annoying to enforce that?

On  Jun 3, 2009, at 08:43, David M. Lloyd wrote:

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