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
