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
