cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Stefano Mazzocchi <>
Subject Re: Public/Private classification (was Re: javadocs navigation)
Date Sat, 15 Oct 2005 16:08:53 GMT
Reinhard Poetz wrote:
> Stefano Mazzocchi wrote:
>> Reinhard Poetz wrote:
>>> Stefano Mazzocchi wrote:
>>>> Daniel Fagerstrom wrote:
>>> [...]
>>>> Daniel,
>>>> let me repeat: I don't care about precision and elegance and 
>>>> completeness, I care about usability.
>>>> I am thinking at flow users that want to use java components to do 
>>>> their stuff. They should *NOT* care about 
>>>> org.apache.cocoon.xml.XMLPipe.
>>> Not all Cocoon users are flow users only ...
>> Reinhard, how many cocoon users have ever implemented 
>> org.apache.cocoon.xml.XMLPipe?
>> My point is not about flow, is about brevity over completeness.
> Stefano,
> TBH I have no strong opinion whether XMLPipe should be part of the 
> public _documentation_.  Of course it is part of the _public API_ 
> because otherwise you're not able to implement e.g. a transformer, but 
> I'm sure that you know this as you're the author of this interface ;-)
> I only doubt that the proposed way of how to find the classes and 
> interfaces, that should become part of the public documentation, will 
> lead to success. Do you guys really think that many people will start to 
> evaluate ~670 classes and interfaces? And if yes, Daniel, Vadim you and 
> me can't agree whether the interface XMLPipe is public or not. So I'm 
> not really optimistice about the outcome as we have to discuss the other 
> 669 classes and interfaces too.
> I'm just with Daniel that we should talk about the principles of what is 
> public and private first.
> After agreeing on them one person can move the public interfaces and 
> classes into a seperate directoy and then we can create a cocoon-api.jar 
> and can create javadocs out of it.
> If you or others think that the "wiki way" of tagging classes is more 
> successful (and faster), please go for it. Believe me, it's not my 
> intention to block this, especially as I don't have the time to work on 
> the alternative within the next 3-4 weeks.

Boy, this is getting frustrating.

I don't give a proverbial f*&k on how we do it the fact is that there 
are many levels of "public API" and we are not acknoledging that, 
nowhere something like this can be found.

In the past, we wanted FOM to be the only interface between flowscript 
and the rest of the system but given how many services are embedded in 
components and how many things were never added to FOM but just expected 
to be discovered out of getComponent(), which means that you need to 
know the entire cocoon internals to be able to write a simple 
flowscript, which is totally ridiculous.

You want principles? here they are:

  1) script-oriented people, those who don't know java and don't care, 
those looking for RAD, those coming from the client or from the XML 
world, should have a reduced API which includes FOM + useful components 
+ environment API and no cocoon internals.

  2) for power users, willing to extend cocoon, the cocoon internal APIs 
(pipelines, caching, input modules, etc..)

  3) for cocoon devepers, everything but at least packaged by block.

This is what I want.

I don't care if we do it by hand or we do it by javadoc or by other means.

I don't care if we use wikis or post-its to find out which interface 
goes in which category(s), or if we use tags or even if we use embedded 
RDF in the javadoc comments for it.

All I want is to help our users stick around... because honestly, I find 
myself in the very uncomfortable position of suggesting people *NOT*TO* 
use cocoon, because is such a horrible climb to get to that comfortable 
plateau of productivity and this is honestly not acceptable today.


View raw message