PHP Function Comments

Question

Just a quick question  I ve seen that some PHP functions are commented at the top  using a format that is unknown to me             Convert an object to an array        param    object   object The object to convert     return      array          My IDE gives me a dropdown selection for the things such as  param and  return  so it must be documented somewhere  I ve tried searching google but it won t include the   symbol in its search   What is this format of commenting and where can I find some information on it

User · Accepted Answer

That s phpDoc syntax   Read more here  phpDocumentor

User · Answer

You must check this  Docblock Comment standards  http   pear php net manual en standards sample php

User · Answer

Functions          Does something interesting        param Place    where  Where something interesting takes place     param integer  repeat How many times something interesting should happen         throws Some Exception Class If something interesting cannot happen     author Monkey Coder  lt mcoder facebook com gt      return Status        Classes          Short description for class       Long description for class  if any            copyright  2006 Zend Technologies     license    http   www zend com license 3 0 txt   PHP License 3 0     version    Release   package version      link       http   dev zend com package PackageName     since      Class available since Release 1 2 0        Sample File    lt  php         Short description for file       Long description for file  if any           PHP version 5 6       LICENSE  This source file is subject to version 3 01 of the PHP license    that is available through the world-wide-web at the following URI     http   www php net license 3 01 txt   If you did not receive a copy of    the PHP License and are unable to obtain it through the web  please    send a note to license php net so we can mail you a copy immediately         category   CategoryName     package    PackageName     author     Original Author  lt author example com gt      author     Another Author  lt another example com gt      copyright  1997-2005 The PHP Group     license    http   www php net license 3 01 txt  PHP License 3 01     version    SVN   Id      link       http   pear php net package PackageName     see        NetOther  Net Sample  Net Sample       since      File available since Release 1 2 0     deprecated File deprecated in Release 2 0 0             This is a  Docblock Comment   also known as a  docblock    The class     docblock  below  contains a complete description of how to write these      require once  PEAR php           constants         Methods return this if they succeed     define  NET SAMPLE OK   1                  GLOBALS         The number of objects created     global int  GLOBALS   NET SAMPLE Count        GLOBALS   NET SAMPLE Count     0                 Net Sample         An example of how to write code to PEAR s standards       Docblock comments start with       at the top   Notice how the        lines up with the normal indenting and the asterisks on subsequent rows    are in line with the first asterisk   The last line of comment text    should be immediately followed on the next line by the closing asterisk    and slash and then the item you are commenting on should be on the next    line below that   Don t add extra lines   Please put a blank line    between paragraphs as well as between the end of the description and    the start of the  tags   Wrap comments before 80 columns in order to    ease readability for a wide variety of users        Docblocks can only be used for programming constructs which allow them     classes  properties  methods  defines  includes  globals    See the    phpDocumentor documentation for more information     http   phpdoc org tutorial phpDocumentor howto pkg html       The Javadoc Style Guide is an excellent resource for figuring out    how to say what needs to be said in docblock comments   Much of what is    written here is a summary of what is found there  though there are some    cases where what s said here overrides what is said there     http   java sun com j2se javadoc writingdoccomments index html styleguide       The first line of any docblock is the summary   Make them one short    sentence  without a period at the end   Summaries for classes  properties    and constants should omit the subject and simply state the object     because they are describing things rather than actions or behaviors        Below are the tags commonly used for classes   category through  version    are required   The remainder should only be used when necessary     Please use them in the order they appear here   phpDocumentor has    several other tags available  feel free to use them         category   CategoryName     package    PackageName     author     Original Author  lt author example com gt      author     Another Author  lt another example com gt      copyright  1997-2005 The PHP Group     license    http   www php net license 3 01 txt  PHP License 3 01     version    Release   package version      link       http   pear php net package PackageName     see        NetOther  Net Sample  Net Sample       since      Class available since Release 1 2 0     deprecated Class deprecated in Release 2 0 0     class Net Sample              properties                 The status of foo s universe        Potential values are  good    fair    poor  and  unknown           var string  foo             public  foo    unknown                   The status of life        Note that names of private properties or methods must be        preceeded by an underscore          var bool   good             private   good   true                         setFoo                   Registers the status of foo s universe               Summaries for methods should use 3rd person declarative rather        than 2nd person imperative  beginning with a verb phrase                Summaries should add description beyond the method s name  The        best method names are  self-documenting   meaning they tell you        basically what the method does   If the summary merely repeats        the method name in sentence form  it is not providing more        information                Summary Examples             Sets the label               preferred             Set the label                avoid             This method sets the label   avoid                Below are the tags commonly used for methods   A  param tag is        required for each parameter the method has   The  return        and  access tags are mandatory   The  throws tag is required if        the method uses exceptions    static is required if the method can        be called statically   The remainder should only be used when        necessary   Please use them in the order they appear here         phpDocumentor has several other tags available  feel free to use        them                The  param tag contains the data type  then the parameter s        name  followed by a description   By convention  the first noun in        the description is the data type of the parameter   Articles like         a    an   and   the  can precede the noun   The descriptions        should start with a phrase   If further description is necessary         follow with sentences   Having two spaces between the name and the        description aids readability                When writing a phrase  do not capitalize and do not end with a        period             the string to be tested               When writing a phrase followed by a sentence  do not capitalize the        phrase  but end it with a period to distinguish it from the start        of the next sentence             the string to be tested  Must use UTF-8 encoding                Return tags should contain the data type then a description of        the data returned   The data type can be any of PHP s data types         int  float  bool  string  array  object  resource  mixed         and should contain the type primarily returned   For example  if        a method returns an object when things work correctly but false        when an error happens  say  object  rather than  mixed    Use         void  if nothing is returned                Here s an example of how to format examples          lt code gt         require once  Net Sample php                  s   new Net Sample           if  PEAR  isError  s                echo  s- gt getMessage       n                    lt  code gt                Here is an example for non-php example or sample          lt samp gt         pear install net sample         lt  samp gt                 param string  arg1 the string to quote         param int     arg2 an integer of how many problems happened                             Indent to the description s starting point                            for long ones                 return int the integer of the set mode used  FALSE if foo                    foo could not be set          throws exceptionclass  description                 access public         static         see Net Sample   foo  Net Other  someMethod           since Method available since Release 1 2 0         deprecated Method deprecated in Release 2 0 0             function setFoo  arg1   arg2   0                              This is a  Block Comment    The format is the same as            Docblock Comments except there is only one asterisk at the            top   phpDocumentor doesn t parse these                      if   arg1     good      arg1     fair                  this- gt foo    arg1              return 1            elseif   arg1     poor   amp  amp   arg2  gt  1                 this- gt foo    poor               return 2            else               return false                                               Local variables     tab-width  4    c-basic-offset  4    c-hanging-comment-ender-p  nil    End         gt    Source  PEAR Docblock Comment standards

User · Answer

You can get the comments of a particular method by using the ReflectionMethod class and calling - getDocComment     http   www php net manual en reflectionclass getdoccomment php

[php] PHP Function Comments

Examples related to php

Examples related to function

Examples related to comments

Examples related to format

Examples related to phpdoc