I'll second Michael's statement, the documentation may exist but you don't even know it's there unless you already know it's there. Tribal knowledge and all that. Sometimes Google even gets me there.
But the T5 website is NOT my first choice exactly because of its organization, and it *should* be my first choice. Most of my complaints would be alleviated by a simple search capability on the tapestry5 website, the lack thereof is my main difficulty in using it. The organization may make perfect sense to someone who really understands the thinking behind T5, but to new folks, it's a mystery. Clearly lots and lots of work has been put into the Tapestry website and documentation. I imagine it's tempting for people who *have* put the effort into the docs to reply "Read The Field Manual" (Look, it's a public board, "Field" will do). That work would be much more valuable to many more of us if it were searchable. It would certainly reduce my frustration level. Here's an example of trying to find something utterly trivial. Say I want to learn about the @Persist annotation. I go to the top level and click on "annotations", and you get a page that is utterly useless, to whit: http://tapestry.apache.org/tapestry5.1/tapestry5-annotations/ Aha, I look again at the top-level and I find a "Persistent State" link. Nope. http://tapestry.apache.org/tapestry5.1/guide/appstate.html Hmmm, maybe I clicked one link too low, there's the "Persistent page data" link at: http://tapestry.apache.org/tapestry5.1/guide/persist.html Aha! cool, that page talks about @Persist. Except..... it has no example of *how* to implement one of the three strategies. But look! There's a link to the javadoc for @Persist! I'm saved! Nope, that page has no example either. http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/annotations/Persist.html At this point I give up and search the project I'm working on for @Persist and see how utterly simple it is to specify, say, flash persistence because some intrepid soul has ferreted it out and put it in the project already. And this is one of the most trivial things in T5. God help me if I'm looking for something more complex, thank goodness for the jumpstart website.... All that said, I *am* grateful for the work that has gone into this project, I just find this maddening..... There, rant finished.. Erick On Tue, Mar 23, 2010 at 8:47 AM, Michael Gentry <mgen...@masslight.net>wrote: > Most new users don't know where in the JavaDoc to begin looking. I > wasn't suggesting there was no JavaDoc, but I don't consider it to be > the main starting point for a new user (needle in a haystack). It is > something for more advanced users. > > As for: http://tapestry.apache.org/tapestry5.1/tapestry-ioc/injection.html > ... Well, using ComponentResources as an example, that page says: > Injects fields of type ComponentResources. That doesn't really give > any information as to what it does or how it can be used. No link to > examples or other documentation. Also, the injection page is buried > down in the IOC section and is not at the top level. That reduces the > prominence of it and that is mainly what I'm talking about (put the > most prominent stuff one uses in T5 -- components, annotations, > injectables -- in a nice reference at the top). > > Thanks, > > mrg > > > On Tue, Mar 23, 2010 at 2:42 AM, Igor Drobiazko > <igor.drobia...@gmail.com> wrote: > > Why is the javadoc insufficient? All the services are located in few > > packages depending on the module they were created. Some of them are: > > > > > http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/ioc/services/package-frame.html > > > http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/services/package-frame.html > > > http://tapestry.apache.org/tapestry5.1/apidocs/org/apache/tapestry5/hibernate/package-frame.html > > > > Furthermore there is a page describing all the resources that are > > injectable: > > > > http://tapestry.apache.org/tapestry5.1/tapestry-ioc/injection.html > > > > You can also open the page ServiceStatus and read its javadoc, if you > want > > to find an appropriate service: > > > > http://tapestry.apache.org/tapestry5.1/guide/servicestatus.html > > > > In summary I would say this issue should be closed as invalid. Tapestry > has > > over 100 services which are good documented in javadoc. Maybe a wiki > article > > which is maintained by the community is a better choice. page. We could > also > > provide a new annotation @Injectable which is used to mark the interfaces > > that are meant for injection. > > > > On Tue, Mar 23, 2010 at 12:54 AM, Michael Gentry <mgen...@masslight.net > >wrote: > > > >> Created: https://issues.apache.org/jira/browse/TAP5-1070 > >> > >> I'm not sure if what I meant by Injectables makes sense, but basically > >> I meant all things supplied by T5 that you can @Inject (such as > >> ComponentResources). I had been using T5 for 2-3 months and had no > >> idea ComponentResources even existed and then I saw an e-mail to this > >> list by Jun Tsai showing it being used to do something that was > >> precisely what I needed to solve a particular problem. Great timing, > >> but it was also quite lucky. If there was a reference of all things I > >> could inject, I might've been able to read through them and have a > >> much better idea of things that are available. > >> > >> Thanks again! > >> > >> mrg > >> > >> > >> On Mon, Mar 22, 2010 at 3:11 PM, Thiago H. de Paula Figueiredo > >> <thiag...@gmail.com> wrote: > >> > On Mon, 22 Mar 2010 16:48:31 -0300, Michael Gentry < > >> mgen...@masslight.net> > >> > wrote: > >> > > >> >> Hello everyone, > >> > > >> > Hi! > >> > > >> > For annotations, > >> > > >> >> All I'm imagining here is a table for each that lists all of the > >> >> annotations and injectables that ship with Tapestry, a short > >> >> description as to what they do, and perhaps links to > examples/detailed > >> >> explanations of how to use them. Another useful column would be what > >> >> version of Tapestry it was introduced. > >> > > >> > Please post a JIRA about it. Seems a very good suggestion to me. > >> > > >> > -- > >> > Thiago H. de Paula Figueiredo > >> > Independent Java, Apache Tapestry 5 and Hibernate consultant, > developer, > >> and > >> > instructor > >> > Owner, software architect and developer, Ars Machina Tecnologia da > >> > Informação Ltda. > >> > http://www.arsmachina.com.br > >> > > >> > --------------------------------------------------------------------- > >> > To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > >> > For additional commands, e-mail: users-h...@tapestry.apache.org > >> > > >> > > >> > >> --------------------------------------------------------------------- > >> To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > >> For additional commands, e-mail: users-h...@tapestry.apache.org > >> > >> > > > > > > -- > > Best regards, > > > > Igor Drobiazko > > http://tapestry5.de/blog > > > > --------------------------------------------------------------------- > To unsubscribe, e-mail: users-unsubscr...@tapestry.apache.org > For additional commands, e-mail: users-h...@tapestry.apache.org > >
