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

[David M. Lloyd]

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