Re: Questions about phpDocumenter standards.

/** * <describe the file here and what it contains> * * PHP version 5 (or PHP version 4 and 5) * * useful resources are as follows: * * - {@link http://www.domain.tld/path/to/pagea Title of webpage A} * - {@link http://www.domain.tld/path/to/page Title of webpage B} * * Some Project's ClassName classes: * see /path/to/file in filename.zip * * * ideas for optimization * * * blah blah blah * * blah blah blah * * blah blah blah * @author you <you@php.net> * @license http://link.to.license whatever * @version $Id$ * @copyright * @see http://www.domain.tld/path/to/PAGE2 PAGE2chapter.subchapter.section */ In terms of linking to specific pages, if there is a way to pass this information to the pdf through a url, then that will work. Otherwise, you'll want to extract the necessary information. If it's tons of pages, then perhaps re-formatting as html would work better. if you wish to include links to documentation of other projects, use a link to the package and the class like {@link package#classname} and pass that package's files into the documentor. Greg Thomas Anderson wrote: > The start of file A reads something like this: > > // PEAR Header goes here > /* useful resources are as follows: > > Title of webpage A (abbr. PAGEA) > http://www.domain.tld/path/to/pagea > > Title of webpage B (abbr. PAGEB) > http://www.domain.tld/path/to/page > > Some Project's ClassName classes: > see /path/to/file in filename.zip > > --------------------- > > ideas for optimization > > * blah blah blah > * blah blah blah > * blah blah blah > see PAGE2 chapter.subchapter.section */ > > How do I make file A's coding standards be in accord with PEARs? > > Consider webpage A. It's a link to a PDF with quite a few chapters / > subchapters / sections / etc and I reference specific sections in it rather > frequently. So what do I do? Use @link? Where then do I put the > abbrevation? I would like to also include the title so someone atleast > knows what the link is about before clicking on it. Maybe I should omit > that and just leave it up to the reader to figure out? > > And what should I do for subsequent references to specific sections within > that PDF? I'd like to do something like... see PAGEA 14.2.4, but that's > apparently not in accord with PEAR Coding Standards. Maybe I should > instead > just do an @link for each of them and let the reader read through the 50+ > pages to figure out what I'm talking about, each time? If I do that I > might > as well just link to www.google.com for everything I want to document and > let the reader figure out the search string and do the search themselves. > It'd make for really poor documentation I'm not sure what else I can do and > still be in compliance with the PEAR Coding Standards. > > And what about the reference to Some Project's ClassName classes? Maybe I > should just do an @link to the source, hope they never release a new > version > (and perhapes make that link invalid) and let readers figure out which > files, in particular, I'm refering to? At that point, I might as well just > omit the link even though I think it'd help. > > And what about the ideas for optimization? Should I just omit material > that > I think would be helpful simply because the PEAR Coding Standards are rigid > and restrictive? Or am I just not understanding the PEAR documentation > standards? > > Anyway, something that might also help my understanding is if someone redid > the above snippet from file A in the PEAR coding standards. > > Thanks! >