Kommentare für PHP-Klassen und -Funktionen

Question

Ich würde gerne einige Dokumentationskommentare für meine (PHP-)Klasse und ihre Funktionen in einem Standardformat hinzufügen, damit es für andere leichter zu verstehen ist.

Was wäre ein Beispiel dafür, wie Sie Kommentare für die folgende Klasse und Funktion schreiben würden?

Informationen über die Klasse:

Klassenname Fotos: enthält einige Funktionen zum Hochladen von Fotos und zur Anzeige von Fotos. Die Funktionsnamen sind upload() , display() , delete() .

Informationen über die Upload-Funktion:

Uploads the resizes and uploads the image and has few parameters as shown below.

<?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 Stil ist ein ziemlicher Standard und wird von den meisten IDEs und Dokumentationsgeneratoren verstanden.

  /**
   * 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

 /**
 * 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'){
}

Dies ist auch für die automatische Vervollständigung in den meisten bekannten Editoren hilfreich.

Answer 3

Sie sollten sich Folgendes ansehen Doxygen . Wenn Sie deren Syntax befolgen, können Sie nicht nur die Dokumentation automatisch generieren (was eigentlich nicht so nützlich ist), sondern auch die Zend Studio IDE gibt Ihnen Codehinweise bei der automatischen Vervollständigung (d. h., sie zeigt die Dokumentation an, wenn Sie den Funktionsnamen eingeben).

/*! \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 4

Ich würde verwenden Natural Docs . Die Doc-Kommentare sind dank der menschenfreundlichen Formatierung direkt im Code leicht zu lesen:

<?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.
    }