Page 1 of 1

Getting started with PHPDocumentor

Posted: Fri Jul 22, 2005 3:45 pm
by nielsene
I'm trying to start using phpDocumentor on my project now. I've installed the package and run it over my current code (without any special tags) just to see what it can find on its own as they describe.

It works rather well, I'll go back through as I debug/test code to add the important/useful tags. However I'm a little confused as to how to deal with the "legal cruft". E.G. all my files have a header:

Code: Select all

/**
   * This file is part of CompInaBox.                            
   * Copyright 2001-2005. Eric D. Nielsen, All rights reserverd  
   * CompInaBox is available for license under the GPL, see      
   * the COPYING file in the root directory of the install for   
   * the full terms of the GPL.                                  
   *                                                             
   * File: CompetitorListFormatter.inc                           
   * Author: Eric D. Nielsen                                     
   * Change Log: 7/22/05 -- created -- edn                       
  */
after converting my previous comment style to phpDocument style. Now my File isn't really needed. Don't know why I ever had it, so I'll ditch that. Author can be replaced with @author, or just remeoved entirely (following XP guidelines.). Ditto for the changelog (that's what CVS (or other versioning system) is for.

However how to deal with the copyright assignment, GPL notice code. This needs to be at the top of every file, but it seems to get jumbled badly by the phpDocumentor. Any suggestions?

Posted: Fri Jul 22, 2005 4:17 pm
by Revan
@copyright ?

Posted: Fri Jul 22, 2005 4:47 pm
by nielsene
but it seems like you have to stick <br /> into the source code afteer the first line of the copyright information before the license information. IE

Code: Select all

<?php
  /**
   * This file is part of CompInaBox.
   * @copyright Copyright 2001-2005. Eric D. Nielsen, All rights reserverd <br />
   * CompInaBox is available for license under the GPL, see
   * the COPYING file in the root directory of the install for
   * the full terms of the GPL.
   *
   * @author Eric D. Nielsen <nielsene@alum.mit.edu>
   * @package CompInaBox
   * @subpackage Database Tools
   */
Without the <br /> it all runs together. But putting that in the source feels wrong.

Posted: Fri Jul 22, 2005 6:25 pm
by Revan
/**
* @copyright http://www.opensource.org/licenses/gpl-license.php GPL Licensed.
*/



What I do.

Posted: Fri Jul 22, 2005 6:53 pm
by nielsene
Well I'm doing:

Code: Select all

/**
   * Database abstraction layer.
   * This file is part of CompInaBox.
   * @copyright Copyright 2001-2005. Eric D. Nielsen, All rights reserverd.
   * @license http://opensource.org/licenses/gpl-license.php GNU Public License
   * @author Eric D. Nielsen <nielsene@alum.mit.edu>
   *
   * @package CompInaBox
   * @subpackage Database-Tools
   */
And it makes the generated documention look very nice, but I liked the old reference to the COPYING file, as that's the way that the FSF recommends applying the GPL to a project. I guess I'll stick with this method for now, but....

Also, how do you make the "package-level" pages? Ie if I go to the root of my document tree I see a page
titled "Generated Documentation" and with "Generated Documentation... Welcome to Default!" as the content. How do I customize this? I noticed that it picked up my INSTALL and README files and links them along the top, how would I get other toplevel entries, etc?

Their manual does a decent job documenting the tags, but nothing on these kinds of topics....

Posted: Fri Jul 22, 2005 7:09 pm
by Revan
I don't think the documentation is that good.
My mistake, I confused @copyright with @license.

I'm not sure about the other stuff, just started using it.

Posted: Fri Jul 22, 2005 7:12 pm
by nielsene
Well I'll post back if I find anything, but from forum scanning at their sf.net site it looks like you have to use raw DocBook for the pacakage level pages.... grr... Don't think I want to tackle that.... learning to use phpDocumentor and Simpletest at the same time is enough....

Thanks!

[edit: found the -ti option or the title parameter in the ini for at least changing the title of the documenation pages from "Generated Documentation" ]