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

[David M. Lloyd]

Theoretically, it would be completely transparent for regular JavaEE-style 
deployment types at least.  For plain JAR deployments I guess it would 
depend on how we decide to implement it - would dependencies be explicitly 
listed?  Would we have a base classpath that is supplemented by 
user-specified dependencies?  Etc.

Right now it appears that nobody is pursuing modularization.  Hopefully we 
can find a way to get this prioritized.

- DML

On 06/03/2009 05:28 PM, Emmanuel Bernard wrote:
> 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
> 
> _______________________________________________
> jboss-development mailing list
> jboss-development at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/jboss-development