#1
  1. No Profile Picture
    Contributing User
    Devshed Intermediate (1500 - 1999 posts)

    Join Date
    Sep 2006
    Posts
    1,984
    Rep Power
    533

    Recommendations on how to document PHP code


    Okay, I have phpdoc setup and running!

    Next step is documenting my code. The documentation is meant for internal use only (i.e. just me).

    I am trying to get a better understanding on what types of comments to include in the different sections. Many of them are obvious, but I can use some help on others. For instance, what is typically added the the first file descriptions? If the file just contains a class, isn't that same information included under the class descriptions? Most of the documentation for phpdoc just gives generic descriptions such as "This file demonstrates the rich information that can be included in in-code documentation". Is there specific information that I should be included in the various sections. Yes, I know it is up to me to figure out what is important to my particular script, however, I am sure there are general practices that most others do. Maybe just pointing me to some properly documented script would help?

    Thanks

    PHP Code:
    <?php
        
    /**
        * Example for file short description
        * Example for file long description
        * goes here
        * @author John Doe <john.doe@gmail.com>
        * @version 1.0
        * @package pagepackage
        */

        /**
        * Example for class short description
        * Example for class long description
        * goes here
        * @package classpackage
        */
        
    class myclass {
            
    /**
            * Example for variable short description
            * @var integer|string
            */
            
    var $firstvar 6;
            
            
    /**
            * Example for method based on $paramie
            * @param boolean $paramie 
            * @return integer|babyclass
            */
            
    function parentfunc($paramie)
            {
                if (
    $paramie) {
                    return 
    6;
                } else {
                    return new 
    babyclass;
                }
            }
        }
    ?>
  2. #2
  3. Sarcky
    Devshed Supreme Being (6500+ posts)

    Join Date
    Oct 2006
    Location
    Pennsylvania, USA
    Posts
    10,905
    Rep Power
    6351
    If your file contains a single class, the file descriptor can be nothing more than 'class file for classWhatever'. Remember, phpdoc supports other kinds of setups, where there's multiple classes per file, files that are simply functions without classes, constant files, etc. If the entire file contains nothing but one class, which itself is documented, don't worry about it.
    HEY! YOU! Read the New User Guide and Forum Rules

    "They that can give up essential liberty to obtain a little temporary safety deserve neither liberty nor safety." -Benjamin Franklin

    "The greatest tragedy of this changing society is that people who never knew what it was like before will simply assume that this is the way things are supposed to be." -2600 Magazine, Fall 2002

    Think we're being rude? Maybe you asked a bad question or you're a Help Vampire. Trying to argue intelligently? Please read this.
  4. #3
  5. No Profile Picture
    Contributing User
    Devshed Intermediate (1500 - 1999 posts)

    Join Date
    Sep 2006
    Posts
    1,984
    Rep Power
    533
    Thanks Dan,

    What about things like a constructor. Would it be more than "Stuff to do when initiating the object"?

    Do you know of any examples of well commented open source code which I should mimic?

IMN logo majestic logo threadwatch logo seochat tools logo