cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Daniel Fagerstrom <dani...@nada.kth.se>
Subject Re: Public/Private classification (was Re: javadocs navigation)
Date Fri, 14 Oct 2005 09:06:05 GMT
Stefano Mazzocchi wrote:
...

> Daniel,
>
> let me repeat: I don't care about precision and elegance and 
> completeness, I care about usability.

That is great Stefano, you find the the 673 classes and interfaces that 
need to be marked public or private, with usability in mind here: 
http://wiki.apache.org/cocoon/PublicAPIClasses. Go ahead and mark them 
if you haven't allready.

> I am thinking at flow users that want to use java components to do 
> their stuff.

I read your previous mail:

> Here's my principle: since I write all my business logic in flow, I 
> want to know which ones are the things that I can expect to call from 
> flow.

Although Cocoon doesn't have the marked share that we would wish, we 
still have more users than you to care about;) Some of the users write 
custom sitemap components as an example, I think they need good JavaDoc 
as well.

Anyway, to get anywhere you need to be a little bit more concrete about 
what you think should be part of the public API for flow users. Classes 
mentioned in http://cocoon.apache.org/2.1/userdocs/flow/api.html 
obviously need to be part of the API: Request, Response, Session, 
Context, Logger, WebContinuation. PipelineUtil and as you mentioned 
SourceUtil and SourceResolver. Anything more?

> They should *NOT* care about org.apache.cocoon.xml.XMLPipe.

In some cases users don't need to care about what classes or interfaces 
an API class extends or implements. For such cases we need to propagate 
down all documentation from the parent classes.

The other kind of dependency I looked at was what interfaces and classes 
the methods of the "public API" returns and have as arguments. I would 
find it rather frustrating to implement an method in an interface 
without having documentation of the types of the parameters, so I don't 
think that completeness is an unreasonable requirement. But maybe I'm 
the only one, and in that case we don't need to care as I read the 
source anyway ;)

Also I think it is quite good idea to do dependency analysis of our 
interfaces (although I need a better tool), as it help us to find 
dependencies that shouldn't be there. Most of the dependencies I found 
seemed rather reasonable, my main question is about ProcessingExceptions 
dependency on various classes and interfaces in 
org.apache.cocoon.util.location, there seem to be a lot of 
interdependencies in that package. But maybe I got some dependencies 
from the tool that wasn't on the acual API level. I haven't anlyzed what 
is going on in detail.

/Daniel


Mime
View raw message