Defining the public and private APIs (was Re: [RT] The future of our lifecycle extensions in 2.2)

[Sylvain Wallez <sy...@apache.org>]

Unico Hommes wrote:

>Sylvain Wallez wrote:
>  
>
>>Unico Hommes wrote:
>>    
>>
>>>I missed your previous proposal. Do you have a pointer?
>>>      
>>>
>>It's here: http://marc.theaimsgroup.com/?l=xml-cocoon-dev&m=105766229504616&w=2
>>    
>>
>
>Thanks.
>
>I don't really understand the need for javadoc tags. I could be missing the point though.
>  
>

Consider the Xalan API at 
http://xml.apache.org/xalan-j/apidocs/index.html and look at e.g. the 
org.apache.xalan.processor package. Some classes have green "For 
advanced use only" or a red "For internal use only" or nothing (public API).

This is the idea behind an additional javadoc tag: allow this kind or 
warning or, better, filtering of the produced documentation.

>For the developer it adds the overhead of having to maintain more code and the user needs to always consult the documentation to check if it is save to use a certain class or not. Wouldn't it be easier to provide separation between private and public through modules instead?
>
>A user would only have the public classes on their compilation or IDE classpaths so there is no room mistake even.
>  
>

Damn, IDE completion is our ennemy here: as long as private classes are 
in the classpath, the user can be tempted to depend on them. With this 
in mind, I understand the only solution is to phyisically separate the 
public and private classes in separate jars.

Now what do we consider to be the public classes? The public contract we 
want to support is mainly composed of interfaces, abstract 
implementation helpers and some utility classes. This means that all 
concrete implementations of components are considered as private classes 
(i.e. user code should not depend on them).

But this leads to the strange situation where all classes that users 
name in their sitemaps and configuration files are considered to be 
private (e.g. FileGenerator, I18nTransformer, etc) and therefore not 
present in the javadoc nor in the IDE project.

Furthermore, how do we debug a project? The IDE needs access to concrete 
implementations for this. And this means making private classes visible 
to automatic completion and thus breaks the clean jar separation.

Also, consider a sitemap editor plugin for Eclipse that proposes the 
list of available generators for the completion of <map:generator 
src="...">. How can we achieve this if the implementation jars aren't in 
the IDE project?

Mmmmmh...

Thoughts?

Sylvain

-- 
Sylvain Wallez                                  Anyware Technologies
http://www.apache.org/~sylvain           http://www.anyware-tech.com
{ XML, Java, Cocoon, OpenSource }*{ Training, Consulting, Projects }
Orixo, the opensource XML business alliance  -  http://www.orixo.com