Phpdocumentor Learning Usage Records

Phpdocumentor Learning Usage Records

A Phpdocumentor Introduction

Phpdocumentor is a php-written tool for PHP programs with canonical annotations that can quickly generate API documentation with cross-referencing, indexing, and other functions. The old version is Phpdoc, starting from 1.3.0, renamed Phpdocumentor, the new version adds support for PHP5 syntax, and can be converted to pdf,html,chm in several forms by manipulating the document on the client browser.

Phpdocumentor is a very powerful document auto-generation tool that helps us write specification annotations, generate easy-to-understand, well-structured documents, and can help with our code upgrades, maintenance, handover, and more.

Two Those elements can generate documents

function functions

Constant Constants

Class

Interface interface

Trait characteristics

Class Constant constants

Property Properties

Method methods

File files

Include/require declaration contains file declaration

Variable variable

Three Basic format

1.Summary Summary

2.Description Detailed description

3.Tags and annotations tags and annotations

Example:

/**

* Function add to achieve two number of additions

*

* A simple addition calculation, the function accepts two numbers A, B, returns their and C

*

* @param int Addend

* @param int Summand

* @return Integer return value

*

*/

function Add ($a, $b)

{

return $a + $b;

}

?>

Generating documents with the command phpdoc-d Project absolute path-T generated document

As follows:

Add

Integer ADD (int $a, int $b)

[Line 45]

function Add, implement two number of additions

Constants A simple addition calculation, the function accepts two numbers A, B, returns their and C

Parameters

int $a-addend

int $b-Summand

Four Label Details list

Tag	Element	Description
Api	Method	Used to declare whether a structure element can be used as a third-party API
Author	Any	Creator Information
Category	File, class	The directory to which the file or class belongs
Copyright	Any	Copyright information
Deprecated	Any	This tag will be deprecated in a future release
Example	Any	This tag refers to the path of the example code
Filesource	File	Source file output
Global	Variable	Global variables
Ignore	Any	This tag is not included in the document
Internal	Any	This tag is used only in applications and internal libraries
License	File, Class	License information for files and classes
Link	Any	Indicate link relationships between elements and sites
Method	Class	Indicates the Magic method available for the class
Package	File, Class	The package information that the file and class belong to
Param	Method,function	Parameter information for methods and functions
Property	Class	Property information for a class
Property-read	Class	Read-only property information for a class
Property-write	Class	Write-only property information for a class
Return	Method,function	Return values for methods and functions
See	Any	Indicate the source of reference
Since	Any	Elements from that version
Source	Any, except File	Display the source code of an element
Subpackage	File, Class	To indicate a child package of classes and files
Throws	Method,function	Indicates that an element might throw an exception
Todo	Any	Indicates that this element is under development.
Uses	Any	Indicates other elements referenced by the element
Var	Properties	Indicates the properties of a class
Version	Any	Indicates the version of the current element

Five Type

Currently the various types of phpdocumentor elements are required and supported by various tags.

1. Full class name or alias

Use its fully qualified class name (FQCN), which means that the class has a prefix slash to indicate that it is a class, such as full name \phpdocumentor\descriptor\classdescriptor.

Use relative class names, such as \descriptor\classdescriptor.

Aliases of classes, such as use Phpdocumentordescriptorparamdescriptor as Param

2. PHP keyword

String

int or integer

Float

BOOL or Boolean

Array

Resource

Null

Callable

3. Keywords for phpdoc standard

Mixed

void

Object

False or True

Self

Static

$this

4. Union type

/** @return String|null */

Six Run Phpdocumentor

Phpdoc

Phpdoc Run

Phpdoc Project:run

The three above can achieve the same effect.

Parameters:

-d Project source file path

-F Make a project one file

-T directory for document Generation

phpdoc-d path/to/my/project-f path/to/an/additional/file-t Path/to/my/output/folder

Seven Label format

1. @api

Format: @api

For example:

/**

*

* @api

*

*/

2. @author

Format: @author [name] [ ]

For example:

/**

     * @author My Name

     * @author My Name 
 
  

     */

3. @category

Format: @category [description]

For example:

/**

      * @category MyCategory

      */

4. @copyright

Format: @copyright [description]

For example:

/**

      * @copyright 1997-2005 the PHP Group

      */

5. @deprecated

Format: @deprecated [ ] [ ]

For example:

/**

     * @deprecated

     * @deprecated 1.0.0

     * @deprecated No longer used by internal code and not recommended.

     * @deprecated 1.0.0 No longer used by internal code and not recommended.

     */

6. @example

Format: @example [Location] [ [ ]] [ ]

For example:

   /**

     * @example example1.php counting in action.

     * @example Http://example.com/example2.phps counting in action by a 3rd party.

     * @example "My Own example.php" my counting.

     */

7. @filesource

Format: @filesource

For example:

    /**

      * @filesource

      */

8. @global

Format: @global [Type] [name] @global [Type] [description]

For example:

    /**

      * @global String $user

      * @global string Username

      */

9. @ignore

Format: @ignore [ ]

For example:

     /**

      * @ignore

      */

Ten. @internal

Format: @internal [description]

For example:

      /**

        * @internal

        */

@license.

Format: @license [ ] [name]

For example:

     /**

       * @license GPL

       * @license http://opensource.org/licenses/gpl-license.php GNU Public License

       */

@link.

Format: @link [URI] [ ]

{@link [URI] [ ]}

For example:

      /**

        * @link Http://example.com/my/bar documentation of Foo.

        * This function would add one as there must always be one Foo.

        */

@method.

Format: @method [return type] [name] ([[[Type] [Parameter]<, ...]) [ ]

For example:

      /**

        * @method string getString ()

        * @method void Setinteger (integer $integer)

        * @method setString (integer $integer)

        */

@package

Format: @package [Level 1]\[level 2]\[etc.]

For example:

      /**

        * @package Psr\documentation\api

        */

@param.

Format: @param [Type] [name] [ ]

For example:

      /**

        * @param mixed[] $ITEMS Array structure to count the elements of.

        */

16. @property

Format: @property [Type] [name] [ ]

For example:

       /**

         * @property String $myProperty

         */

@property-read

Format: @property-read [Type] [name] [<>< p=""> <>

       For example:

/**

         * @property-read string $myProperty

         */

@property-write

Format: @property-write [Type] [name] [ ]

For example:

      /**

        * @property-write string $myProperty

        */

19. @return

Format: @return [Type] [ ]

For example:

       /**

         * @return Integer indicates the number of items.

         * @return string|null the label ' s text or null if none provided.

         */

@see

Format: @see [URI | Fqsen] [ ]

For example:

      /**

        * @see Http://example.com/my/bar documentation of Foo.

        * @see MyClass:: $items for the property whose items is counted.

        * @see Myclass::setitems () to set the items for this collection.

        */

@since.

Format: @since [version] [ ]

For example:

    /**

      * @since 1.0.2 Added the $b argument.

      * @since 1.0.1 Added the $a argument.

      * @since 1.0.0

      *

      */

      function dump ($a, $b)

      {

          <...>

      }

@source.

Format: @source [ [ ]] [ ]

For example:

    /**

      * @source 2 1 Check that ensures lazy counting.

      */

@subpackage.

Format: @subpackage [name]

For example:

    /**

      * @package PSR

      * @subpackage Documentation\api

      */

@throws

Format: @throws [Type] [ ]

For example:

    /**

      * of  type ' array '.

      */

@todo

Format: @todo [description]

For example:

    /**

      * @todo add an array parameter to count

  */

@uses

Format: @uses [Fqsen] [ ]

For example:

    /**

      * @uses MyClass:: $items to retrieve the count from.

     */

@var.

Format: @var ["Type"] [$element _name] [ ]

For example:

    /** @var String|null should contain a description

      * @var string $name        should contain a description

      * @var string $description should contain a description

      */

@version.

Format: @version [ ] [ ]

    /**

      * @version 1.0.1

      * @version GIT: $Id $ in development. Very unstable.

      */

