Sorry for the delay. Have been taking a few days off from the computer. Sylvain Wallez wrote: > > 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). >
Wow, if adopting such tags promotes their kind of javadoc verbosity .. I want it! ;-) Seriously, I should have looked at them after being clueless. I agree that the way they are using those annotations looks very nice. > 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. > OK, emphasis is good ;-) > 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. > Hmm, 'privateness' does not exclude them from javadoc membership per se. > 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? > I think you are making valid points for development within IDEs. Dividing a system into logical units brings a lot of benefits. One thing it does is that it helps define the intended use of different sets of classes. Both to users and developers. A physical seperation like this is one of the ways in which to make such intention explicit. Your arguments show it is not enough to prevent users from using internal-only intended code. So perhaps we need both physical separation and javadoc level annotations. >From a code functional point of view I would also like to see a seperation of API level classes and SPI level classes. Both of these sets will be entirely public. Unico
