Re: Public/Private classification (was Re: javadocs navigation)
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.
--
Reinhard Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
Re: Public/Private classification (was Re: javadocs navigation)
On 15.10.2005 10:38, Reinhard Poetz wrote: 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. Amen. Jörg
Re: Public/Private classification (was Re: javadocs navigation)
Vadim Gritsenko wrote:
Stefano Mazzocchi wrote:
Reinhard Poetz wrote:
Reinhard, how many cocoon users have ever implemented
org.apache.cocoon.xml.XMLPipe?
All users who implemented at least one Transformer.
public interface Transformer extends XMLPipe, SitemapModelComponent {
}
If you are implementing transformer for a first time, you have to have
javadocs (or source code (or IDE with reflection)) to implement it.
I don't think you guys understand what I'm saying.
For each user that needs to write a transformer, there are 20 users that
don't, but if they go all to the same place, only the user that is able
to write transformers will stick around.
which is *exactly* what's happening.
So, we can keep the same attitude, or change it.
I'm for changing it.
--
Stefano.
Re: Public/Private classification (was Re: javadocs navigation)
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. -- Stefano.
Re: Public/Private classification (was Re: javadocs navigation)
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
Re: Public/Private classification (was Re: javadocs navigation)
Stefano Mazzocchi wrote: Daniel Fagerstrom wrote: Daniel Fagerstrom wrote: To illustrate what I meant I tried to follow the dependencies for the sitemap component interfaces. Cocoon API == So what is the Cocoon API? All interfaces used in cocoon-core-sitemap.xconf are part of the Cocoon API: Generator, Transformer, Serializer, Reader, Matcher, Selector, Action, ProcessingPipeline. Then the interfaces refered to in the Cocoon API must be part of the API as well by transitive closure. So here we get various exceptions, SitemapModelComponent, XMLPipe, XMLProducer and much more. The ObjectModelHelper with dependencies is also part of the API. Starting with: org.apache.cocoon.acting.Action org.apache.cocoon.generation.Generator org.apache.cocoon.matching.Matcher org.apache.cocoon.reading.Reader org.apache.cocoon.selection.Selector org.apache.cocoon.serialization.Serializer org.apache.cocoon.transformation.Transformer (I removed the ProcessingPipeline as it dependencies seem to explode to all kinds of internal classes, we need to polish that interface if it should be considered public) These interfaces depends on: org.apache.avalon.framework.parameters.Parameters org.apache.cocoon.ProcessingException org.apache.cocoon.environment.Redirector org.apache.cocoon.environment.SourceResolver org.apache.cocoon.sitemap.SitemapModelComponent org.apache.cocoon.sitemap.SitemapOutputComponent org.apache.cocoon.sitemap.PatternException org.apache.cocoon.xml.XMLConsumer org.apache.cocoon.xml.XMLPipe org.apache.cocoon.xml.XMLProducer which depends on (skipping the avalon dependencies) org.apache.avalon.framework.CascadingException org.apache.cocoon.util.location.LocatedException (org.apache.cocoon.util.location.LocatedRuntimeException) org.apache.cocoon.util.location.Location org.apache.cocoon.util.location.MultiLocatable and again org.apache.cocoon.util.location.Locatable org.apache.cocoon.util.location.LocatableException org.apache.cocoon.util.location.LocationImpl org.apache.cocoon.util.location.LocationUtils org.apache.commons.lang.exception.NestableException org.apache.commons.lang.exception.ExceptionUtils === The object model helper must also be considered to be part of the Cocoon API, there we get the dependencies: org.apache.cocoon.environment.ObjectModelHelper -- org.apache.cocoon.environment.Context org.apache.cocoon.environment.Request org.apache.cocoon.environment.Response -- org.apache.cocoon.environment.Cookie org.apache.cocoon.environment.Session === This should be a complete list of the public sitemap component API (I did the dependency analysis semi automatically with http://depfind.sourceforge.net/, so I could have done some mistakes). It's not complete - at least InputModule interface is missing, may be something else. But it is a good start. A similar list for the public component API, starting from cocoon-core.xconf would also be a good idea. But I would need a better tool than depfind for that excercise, any suggestions? I am not sure everything declared in the cocoon.xconf is public API, although most of the stuff is, such as xml parser, xslt processor, runnable manager, etc. I'm not suggesting that we can find out the Cocoon API automatically. But given that we want a particular set of interfaces in the public API and JavaDoc, I think it would be rather strange if we didn't made all the o.a.c interfaces and classes that these interfaces depends on also part of the public API. 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. Users that write *own* components *do* care about XMLPipe. Vadim
Re: Public/Private classification (was Re: javadocs navigation)
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.
Re: Public/Private classification (was Re: javadocs navigation)
Stefano Mazzocchi wrote:
Reinhard Poetz wrote:
Reinhard, how many cocoon users have ever implemented
org.apache.cocoon.xml.XMLPipe?
All users who implemented at least one Transformer.
public interface Transformer extends XMLPipe, SitemapModelComponent {
}
If you are implementing transformer for a first time, you have to have javadocs
(or source code (or IDE with reflection)) to implement it.
Vadim
Re: Public/Private classification (was Re: javadocs navigation)
Upayavira wrote: So, I have created a wiki page: http://wiki.apache.org/cocoon/PublicAPIClasses Please go there and mark classes public/private as necessary. As it says at the top of that page, if you disagree with someone, change it to dispute or D for short. Then it becomes an opportunity for some healthy argument! Wow! that's a lot of classes. While I aplaud the initiative, 673 classes are huge amount to classify. I would suggest that we start discussing principles first a bit. IMO we need to find two set of interfaces/classes: the API of Cocoon, and the set of classes (components) that an application programmer need JavaDoc for. I guess this thread is mainly about the second set, but I find it hard to adress whoyhout discussing the first one. Cocoon API == These are the interfaces that we intend an application programmer to implement while building Cocoon applications. Our contract with the user is that we do our best to keep these interfaces. And when that would be a to large hinder for further development of Cocoon, we follow standard practices for deprecation or interface modification. We should IMO put the Cocoon API in one or possibly several pure interface jars (bundles). So what is the Cocoon API? All interfaces used in cocoon-core-sitemap.xconf are part of the Cocoon API: Generator, Transformer, Serializer, Reader, Matcher, Selector, Action, ProcessingPipeline. Then the interfaces refered to in the Cocoon API must be part of the API as well by transitive closure. So here we get various exceptions, SitemapModelComponent, XMLPipe, XMLProducer and much more. The ObjectModelHelper with dependencies is also part of the API. Then we can continue to take a look at cocoon-core.xconf. Most of the interfaces used here are probably part of the Cocoon API: InputModule, OutputModule, Source (with extending interfaces: WritableSource and maybe some more), to mention some obvious. For some of the interfaces here it is less clear if they are part of the Cocoon API, as an example are we going to support the use of Processor? To connect to a current discussion. Maybe there are part of the Cocoon API that not is used for components and sitemap components? We obviously support Servlet e.g. Public API Classes This is what a user needs to build own components, use components from flowscript or using Cocoon from other applications or environments. Here we have all (or most) components defined in cocoon-core-sitemap.xconf and cocoon-core.xconf. The CocoonBean and CocoonServlet would also be part of this. Some utility classes from util and xml and abstract classes that helps implementing different component classes could also be part of the public API classes. --- o0o --- So if you think that the above is a good idea, we could work incrementally: Start with defining the Cocoon API: one list of sitemap component interfaces, one with component interfaces and one where people could add other intefaces that should be part of the Cocoon API. Then we could mark what should be public and private in these lists. We also need to have a list with the transitive closure of all interfaces and classes that the previous lists depends on (hopefully some IDE or other tool can generate that list). As the dependencies also need to be part of the Cocoon API. This will also give as an indication if there are parts of Cocoon that would need to be refactored to give cleaner and more focused interfaces. When we have agreed about what is the Cocoon API, I would be happy if we could move it to an own jar. After or in parallell with finding the Cocoon API, we could work on the public API classes, following similar principles. Listing all components from our configuration for marking them public or private and also utility classes. And then a list of the transitive closure of the dependencies. Also the public API classes should go to one or several component bundles. WDYT? /Daniel
Re: Public/Private classification (was Re: javadocs navigation)
Daniel Fagerstrom wrote: Upayavira wrote: So, I have created a wiki page: http://wiki.apache.org/cocoon/PublicAPIClasses Please go there and mark classes public/private as necessary. As it says at the top of that page, if you disagree with someone, change it to dispute or D for short. Then it becomes an opportunity for some healthy argument! Wow! that's a lot of classes. While I aplaud the initiative, 673 classes are huge amount to classify. I would suggest that we start discussing principles first a bit. 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. Documenting FOM is one thing, but then we have a bunch of other things (like SourceUtil and excalibur resolver etc) that I use all the time. So, my rationale is not to document XMLPipe (since I'll never use it or implement it in flow) but to have an idea, from the cocoon user point of view, of where are the hooks. So, there are 4 levels: 1) FOM (the javascript objects available to flow) 2) the static java utils + avalon components 3) the cocoon interfaces 4) the cocoon classes we document #1 (badly, if you ask me, it's a pain to find) and the rest is one huge bundled javadoc and our class classification by package does *NOT* induce itself to the classification above (maybe #3 and #4, given that we use impl to indicate what implements an interface, and we use .components even if not all of those are meant to be used in flow) If we want to appeal to the users, we need to tell them loud and clear what are the hooks they can use. Otherwise, it feels like flying without a net. Some people here want to move to javaflow to have eclipse do the work for them, I think we have to do something anyway. -- Stefano.
Re: Public/Private classification (was Re: javadocs navigation)
Daniel Fagerstrom wrote: ... To illustrate what I meant I tried to follow the dependencies for the sitemap component interfaces. Cocoon API == ... So what is the Cocoon API? All interfaces used in cocoon-core-sitemap.xconf are part of the Cocoon API: Generator, Transformer, Serializer, Reader, Matcher, Selector, Action, ProcessingPipeline. Then the interfaces refered to in the Cocoon API must be part of the API as well by transitive closure. So here we get various exceptions, SitemapModelComponent, XMLPipe, XMLProducer and much more. The ObjectModelHelper with dependencies is also part of the API. Starting with: org.apache.cocoon.acting.Action org.apache.cocoon.generation.Generator org.apache.cocoon.matching.Matcher org.apache.cocoon.reading.Reader org.apache.cocoon.selection.Selector org.apache.cocoon.serialization.Serializer org.apache.cocoon.transformation.Transformer (I removed the ProcessingPipeline as it dependencies seem to explode to all kinds of internal classes, we need to polish that interface if it should be considered public) These interfaces depends on: org.apache.avalon.framework.parameters.Parameters org.apache.cocoon.ProcessingException org.apache.cocoon.environment.Redirector org.apache.cocoon.environment.SourceResolver org.apache.cocoon.sitemap.SitemapModelComponent org.apache.cocoon.sitemap.SitemapOutputComponent org.apache.cocoon.sitemap.PatternException org.apache.cocoon.xml.XMLConsumer org.apache.cocoon.xml.XMLPipe org.apache.cocoon.xml.XMLProducer which depends on (skipping the avalon dependencies) org.apache.avalon.framework.CascadingException org.apache.cocoon.util.location.LocatedException (org.apache.cocoon.util.location.LocatedRuntimeException) org.apache.cocoon.util.location.Location org.apache.cocoon.util.location.MultiLocatable and again org.apache.cocoon.util.location.Locatable org.apache.cocoon.util.location.LocatableException org.apache.cocoon.util.location.LocationImpl org.apache.cocoon.util.location.LocationUtils org.apache.commons.lang.exception.NestableException org.apache.commons.lang.exception.ExceptionUtils === The object model helper must also be considered to be part of the Cocoon API, there we get the dependencies: org.apache.cocoon.environment.ObjectModelHelper -- org.apache.cocoon.environment.Context org.apache.cocoon.environment.Request org.apache.cocoon.environment.Response -- org.apache.cocoon.environment.Cookie org.apache.cocoon.environment.Session === This should be a complete list of the public sitemap component API (I did the dependency analysis semi automatically with http://depfind.sourceforge.net/, so I could have done some mistakes). === A similar list for the public component API, starting from cocoon-core.xconf would also be a good idea. But I would need a better tool than depfind for that excercise, any suggestions? === I'm not suggesting that we can find out the Cocoon API automatically. But given that we want a particular set of interfaces in the public API and JavaDoc, I think it would be rather strange if we didn't made all the o.a.c interfaces and classes that these interfaces depends on also part of the public API. /Daniel
Re: Public/Private classification (was Re: javadocs navigation)
Daniel Fagerstrom wrote: Daniel Fagerstrom wrote: ... To illustrate what I meant I tried to follow the dependencies for the sitemap component interfaces. Cocoon API == ... So what is the Cocoon API? All interfaces used in cocoon-core-sitemap.xconf are part of the Cocoon API: Generator, Transformer, Serializer, Reader, Matcher, Selector, Action, ProcessingPipeline. Then the interfaces refered to in the Cocoon API must be part of the API as well by transitive closure. So here we get various exceptions, SitemapModelComponent, XMLPipe, XMLProducer and much more. The ObjectModelHelper with dependencies is also part of the API. Starting with: org.apache.cocoon.acting.Action org.apache.cocoon.generation.Generator org.apache.cocoon.matching.Matcher org.apache.cocoon.reading.Reader org.apache.cocoon.selection.Selector org.apache.cocoon.serialization.Serializer org.apache.cocoon.transformation.Transformer (I removed the ProcessingPipeline as it dependencies seem to explode to all kinds of internal classes, we need to polish that interface if it should be considered public) These interfaces depends on: org.apache.avalon.framework.parameters.Parameters org.apache.cocoon.ProcessingException org.apache.cocoon.environment.Redirector org.apache.cocoon.environment.SourceResolver org.apache.cocoon.sitemap.SitemapModelComponent org.apache.cocoon.sitemap.SitemapOutputComponent org.apache.cocoon.sitemap.PatternException org.apache.cocoon.xml.XMLConsumer org.apache.cocoon.xml.XMLPipe org.apache.cocoon.xml.XMLProducer which depends on (skipping the avalon dependencies) org.apache.avalon.framework.CascadingException org.apache.cocoon.util.location.LocatedException (org.apache.cocoon.util.location.LocatedRuntimeException) org.apache.cocoon.util.location.Location org.apache.cocoon.util.location.MultiLocatable and again org.apache.cocoon.util.location.Locatable org.apache.cocoon.util.location.LocatableException org.apache.cocoon.util.location.LocationImpl org.apache.cocoon.util.location.LocationUtils org.apache.commons.lang.exception.NestableException org.apache.commons.lang.exception.ExceptionUtils === The object model helper must also be considered to be part of the Cocoon API, there we get the dependencies: org.apache.cocoon.environment.ObjectModelHelper -- org.apache.cocoon.environment.Context org.apache.cocoon.environment.Request org.apache.cocoon.environment.Response -- org.apache.cocoon.environment.Cookie org.apache.cocoon.environment.Session === This should be a complete list of the public sitemap component API (I did the dependency analysis semi automatically with http://depfind.sourceforge.net/, so I could have done some mistakes). === A similar list for the public component API, starting from cocoon-core.xconf would also be a good idea. But I would need a better tool than depfind for that excercise, any suggestions? === I'm not suggesting that we can find out the Cocoon API automatically. But given that we want a particular set of interfaces in the public API and JavaDoc, I think it would be rather strange if we didn't made all the o.a.c interfaces and classes that these interfaces depends on also part of the public API. 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. -- Stefano.
Re: Public/Private classification (was Re: javadocs navigation)
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 Pötz Independent Consultant, Trainer (IT)-Coach
{Software Engineering, Open Source, Web Applications, Apache Cocoon}
web(log): http://www.poetz.cc
RE: javadocs navigation (was: [RT] Is Cocoon Obsolete?)
... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Can't you use the refdoc stuff for that? If it's not ready, which I guess it isn't from the STATUS at http://svn.apache.org/repos/asf/cocoon/gsoc/rgraham/refdoc/STATUS, I could take it from where Robert left it... WDYT? max
Re: javadocs navigation (was: [RT] Is Cocoon Obsolete?)
On 12.10.2005, at 08:20, Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Hm... if you cannot navigate with the current javadocs navigation it's a clear sign that the codebase needs some refactoring - not a better navigation IMHO. Although something like that *would* be sexy ;) cheers -- Torsten PGP.sig Description: This is a digitally signed message part
Re: javadocs navigation (was: [RT] Is Cocoon Obsolete?)
Le 12 oct. 05, à 09:32, Max Pfingsthorn a écrit : ...Can't you use the refdoc stuff for that? If it's not ready, which I guess it isn't from the STATUS at http://svn.apache.org/repos/asf/cocoon/gsoc/rgraham/refdoc/STATUS, I could take it from where Robert left it... It's not far from being usable I think, what it needs most is a good example of what it can bring. I haven't had time to have a deeper look in my Bursty Copious Free Time yet, but if you want to have a look you're very welcome, I'll do my best to help! -Bertrand
Re: javadocs navigation
Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. Sylvain -- Sylvain WallezAnyware Technologies http://people.apache.org/~sylvain http://www.anyware-tech.com Apache Software Foundation Member Research Technology Director
Re: javadocs navigation
Sylvain Wallez wrote: Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. And now, it's time for Guido to show up again - as he proposed this a long time ago and I think he already implemented something. But I might be wrong... Carsten -- Carsten Ziegeler - Open Source Group, SN AG http://www.s-und-n.de http://www.osoco.org/weblogs/rael/
Re: javadocs navigation
Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. All right, here's another thing that could help this project: do it hacky now instead of doing it cool later. I'm partially responsible for leading the community to think that hacks don't work (and they don't, in the long run) but in the short run, something as small as having another javadoc, built with just a subset of the code, would be good enough... We have been working on ways to improve stuff forever, but everytime somebody comes up with an idea, somebody comes up with another idea, more elegant, more general, more scalable and harder to implement... and it creates a stall: either somebody implements the more elegant idea or nothing happens at all. I think this is our single most important problem in helping our users: we care too much about them and we want to give them the best experience we can think of. We need to start caring less about that. -- Stefano.
Re: javadocs navigation
Sylvain Wallez wrote: Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. There you go! +1 -- Stefano.
Re: javadocs navigation
Stefano Mazzocchi wrote: Sylvain Wallez wrote: Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. There you go! +1 So how do we decide what is internal, what is external? The discussion is likely to be fun. We could have a wiki page containing all classes, and mark the ones on that wiki page that we want to be public. Then a script could add the necessary javadoc markup. If that approach sounds okay, I'd happily volunteer to write the script to add the markup, assuming it is a simple enough markup. Thoughts? Regards, Upayavira
Re: javadocs navigation
Upayavira wrote: Stefano Mazzocchi wrote: Sylvain Wallez wrote: Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. There you go! +1 So how do we decide what is internal, what is external? The discussion is likely to be fun. Let's start small - let's mark as public, external classes only those where we have consensus, and leave questionable classes out, have a discussion on them later. We could have a wiki page containing all classes, and mark the ones on that wiki page that we want to be public. Then a script could add the necessary javadoc markup. Wiki page, where each java class can be marked as one of: public / private / dispute / not-marked-yet. If that approach sounds okay, I'd happily volunteer to write the script to add the markup, assuming it is a simple enough markup. Sounds good Vadim
Re: javadocs navigation
Upayavira wrote: Stefano Mazzocchi wrote: Sylvain Wallez wrote: Bertrand Delacretaz wrote: Le 12 oct. 05, à 05:16, Stefano Mazzocchi a écrit : ...I think a better, leaner, cleaner javadoc would go a *LNG* way to make things easier... I was thinking about that recently - does anyone know a tool for tag-based navigation of javadocs? A better *navigation* of the javadocs, like being able to see all classes which have the sitemap generator tags, would help a lot. Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. There you go! +1 So how do we decide what is internal, what is external? The discussion is likely to be fun. Yeah, well, we are reasonable people ( sometimes ;-) We could have a wiki page containing all classes, and mark the ones on that wiki page that we want to be public. Then a script could add the necessary javadoc markup. If that approach sounds okay, I'd happily volunteer to write the script to add the markup, assuming it is a simple enough markup. Thoughts? Sounds good to me. -- Stefano.
Public/Private classification (was Re: javadocs navigation)
So, I have created a wiki page: http://wiki.apache.org/cocoon/PublicAPIClasses Please go there and mark classes public/private as necessary. As it says at the top of that page, if you disagree with someone, change it to dispute or D for short. Then it becomes an opportunity for some healthy argument! On with the asbestos underwear everyone... Upayavira Vadim Gritsenko wrote: Upayavira wrote: Stefano Mazzocchi wrote: Sylvain Wallez wrote: Or more simpler, and we already talked about this, what about tagging the source files themselves to be able to produce javadocs of a restricted set of classes, i.e. those that are considered public API and that people can safely rely on. There you go! +1 So how do we decide what is internal, what is external? The discussion is likely to be fun. Let's start small - let's mark as public, external classes only those where we have consensus, and leave questionable classes out, have a discussion on them later. We could have a wiki page containing all classes, and mark the ones on that wiki page that we want to be public. Then a script could add the necessary javadoc markup. Wiki page, where each java class can be marked as one of: public / private / dispute / not-marked-yet. If that approach sounds okay, I'd happily volunteer to write the script to add the markup, assuming it is a simple enough markup. Sounds good Vadim
Re: javadocs navigation
Stefano Mazzocchi wrote: I think this is our single most important problem in helping our users: we care too much about them and we want to give them the best experience we can think of. We need to start caring less about that. In short: Perfect is the enemy of good. Bye, Helma
Re: javadocs navigation
Niclas Hedhman wrote: On Wednesday 12 October 2005 23:59, Stefano Mazzocchi wrote: I think this is our single most important problem in helping our users: we care too much about them and we want to give them the best experience we can think of. And ironically giving users a harder time :o) well, not a harder time, but harder than giving them something to start with even if not perfect or elegant or not showing how cool we can do things. Very interesting observation I must say. I will indeed place that on my daily reminder section on the whiteboard. Too good to forget. And can be applied to many facets of life. Oh yes, ask my girlfriend about it: she gets nuts when I try so hard to have a solution for a problem she has and all she is looking for is a hug ;-) -- Stefano.
Re: Public/Private classification (was Re: javadocs navigation)
Upayavira wrote: So, I have created a wiki page: http://wiki.apache.org/cocoon/PublicAPIClasses Please go there and mark classes public/private as necessary. As it says at the top of that page, if you disagree with someone, change it to dispute or D for short. Then it becomes an opportunity for some healthy argument! On with the asbestos underwear everyone... I would suggest to start by saying N to every class that is not yet tagged move it from there. I would also suggest to add all the other avalon components we ship by default too (I use the SourceResolver quite a bit and you need to pass this to the SourceUtil.getSource() so you need to get it somewhere) Note: yes, I write all my application logic in javascript these days and I don't care if it's bad or I don't have eclipse for it having a better javadoc would be just enough. -- Stefano.
Re: javadocs navigation
hepabolu wrote: Stefano Mazzocchi wrote: I think this is our single most important problem in helping our users: we care too much about them and we want to give them the best experience we can think of. We need to start caring less about that. In short: Perfect is the enemy of good. and Good is not really a friend of good enough either ;-) -- Stefano.
[OT] Re: javadocs navigation
Stefano Mazzocchi wrote: Oh yes, ask my girlfriend about it: she gets nuts when I try so hard to have a solution for a problem she has and all she is looking for is a hug ;-) Hehe. This is a very common misunderstanding between men and women: men try to find a solution to what is actually not a problem, but a call for communication ;-) Sylvain -- Sylvain WallezAnyware Technologies http://people.apache.org/~sylvain http://www.anyware-tech.com Apache Software Foundation Member Research Technology Director
Re: Public/Private classification (was Re: javadocs navigation)
Stefano Mazzocchi wrote: Upayavira wrote: So, I have created a wiki page: http://wiki.apache.org/cocoon/PublicAPIClasses I would also suggest to add all the other avalon components we ship by default too (I use the SourceResolver quite a bit and you need to pass this to the SourceUtil.getSource() so you need to get it somewhere) Yep, can we have please avalon-framework, excalibur-* classes in there too? May be on separate page? LOTS of those classes, me thinks, are our public API. Vadim
