Stefano Mazzocchi wrote: ...

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 read your previous mail:

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?

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