RE: [PEAR-DEV] RE: [PEAR-DOC] phpDocumentor tutorials/extended do cumentation imp lementation

I begin to see your point of view more clearly now. I'll dig into this when i get back from vacations ;) Arnaud. > No, see ie the PEAR::DB doc. The problem is, only the > maintainer of a package can really write the tutorial, i can > only write > the API doc based on the phpdocs. > > To clearify my position as editor: > > Note: > (end-)user = programmer who wants to use a PEAR package > programmer = programmer/maintainer of an PEAR package > > As user, the docs of the JDK or CPAN drives me often crazy. They are > really API docs only. If i want to get a starting point (tutorial), i > have to go Google and starting a query like "CPAN libwww tutorial". > I get a lot of links to docs in txt, html, pdf, ...; some of > the links > are dead, some content is just unsatiesfied. > After reading the tutorial and getting the idea of "how it works", i > need an API doc only - but not like the JDK API docs; to much stuff: > private functions etc. The same problem in the code docs of > PEAR, a lot > of information refers to internal stuff, nice for a programmer - > senseless and dangerous for a user. > > While thinking about the content of the PEAR manual, i had > this in mind. > My idea of the PEAR Manual is: Keep information for beginners and > advanced user in one place = peardoc. > Tutorials are an starting point for a user, they have to be put into > peardoc, because they have to be up to date and bug free as > possible - > no maintainer can this guarantee for "his tutorial" on a server > somewhere. Also - i'm sure - the most maintainer/programmer > doesn't know > what is in peardoc all together, but i (should) know it as editor. > > I worked on the docs for XML_sql2xml; Christian wrote an really good > tutorial - but it is placed on his server. And it covers information, > which are desrcibed already in the PEAR Manual (installation etc.) - > uninteresting if your are already familar with PEAR. As > editor , i can > drop such section and replace them with links to the section covering > this topics in detail; advanced PEAR user can ignore this. > They are not > forced to read well knowed stuff. > > And for API doc issue - do not confound PHPDoc API doc with > Manual API > Doc. The API doc in the manual should only show the public > interface of > an package. It should give a user the information which > function he can > use and how to use - not how the package is implemented. > Compare the API > entries of the Manual with the API doc entries - they differ > in the most > cases. If you are a programmmer, you have to run > phpdoc(-umentator) over > the source, the manual will not be a replacement for this. > > Ok, a long mail, written in short time, but hopefully you get > i idea of > my thoughts. > > PS: i'm not against the @tutorial tag, but strictly against > using it in > PEAR. >