Comentarios para la clase PHP y sus funciones?

Question

Me gustaría agregar algunos comentarios de documentación para mi clase (PHP) y sus funciones en algún formato estándar para que sea más fácil de entender para otros.

Agradeceré si me puede dar un ejemplo de cómo escribiría comentarios para seguir la clase y la función? Gracias.

información acerca de la clase:

CLASSNAME Fotos: tiene algunas funciones relacionadas con la posibilidad de subir la foto y mostrar las fotos. los nombres de las funciones son upload(), display(), delete().

información acerca de la función de carga:

carga los redimensiona y carga la imagen y tiene unos parámetros como se muestra a continuación.

<?php 
class Photos extends CI_Controller 
{ 
    public function upload($file_name, $new_name, $new_width, $new_height, $directory) 
    { 
     ... 
     ... 
     returns true or false. 
    } 

Answer 1

PHPDocumentor estilo es bastante estándar y comprendido por la mayoría de IDE y generadores de documentación.

/** 
    * Photos 
    * 
    * 
    * @package CI 
    * @subpackage Controller 
    * @author  YOUR NAME <YOUREMAIL@domain.com> 
    */ 
    class Photos extends CI_Controller 
    { 

     /** 
     * 
     * Uploads a file 
     * 
     * @param string $file_name description 
     * @param string $new_name description 
     * @param integer $new_width description 
     * @param integer $new_height description 
     * @param string $directory description 
     * @return boolean 
     */ 
     public function upload($file_name, $new_name, $new_width, new_$height, $directory) 
     { 

     } 
    } 

Answer 2

Es posible que desee mirar doxygen. Si sigue su sintaxis, no solo podrá generar automáticamente la documentación (que en realidad no es tan útil), sino que Zend IDE le dará sugerencias de código sobre autocompletado (es decir, mostrará la documentación cuando empiece a escribir el nombre de la función) .

/*! \brief My Photo Class 
* Does some stuff with photos 
*/ 
class Photos extends CI_Controller 
{ 
    /*! \brief Uploads a file 
    * \param $file_name The name of the file 
    * ... 
    * \returns A value indicating success 
    */ 
    public function upload($file_name, $new_name, $new_width, new_$height, $directory) 
    { 
    ... 
    ... 
    returns true or false. 
    } 
} 

Answer 3

/** 
* A sample function docblock 
* @global string document the fact that this function uses $_myvar 
* @staticvar integer $staticvar this is actually what is returned 
* @param string $param1 name to declare 
* @param string $param2 value of the name 
* @return integer 
*/ 
function firstFunc($param1, $param2 = 'optional'){ 
} 

Esto también será útil para la función de autocompletar en los editores más conocidos

Answer 4

yo usaría Natural Docs. Los comentarios del doc son fáciles de leer en el código gracias al formateo fácil de usar:

<?php 

/* 
    Class: Photos 

    Some functions related to uploading the photo and displaying the photos. 
*/ 
class Photos extends CI_Controller 
{ 
    /* 
     Function: upload 

     Upload a photo to the server so that you can later <display> it. 

     Arguments: 

      file_name - name of the file 
      new_name - name of the file on the server 
      new_width - resize to this before uploading 
      new_height - resize to this before uploading 

     Returns: 

      true or false. 

     See Also: 

      <display> 
      <delete> 
    */    
    public function upload($file_name, $new_name, $new_width, new_$height, $directory) 
    { 
     ... 
     ... 
     returns true or false. 
    }