原文 ： http://kbs.kimbs.cn/blog/list/post/26/title/zend-framework-coding-standards-for-php-inline-documentation
Zend Framework 中的 Php 编码标准 (四) - 内嵌文档
1. Docblocks start always with "/*" or "/**". The use of "#" is not allowed. The "//" is only allowed for comments within functions.
For example :
/**
* Class docblock
*/
class
foo
{
/* Variable docblock */
public
$foo
;
/**
* Function docblock
*/
public function
__construct
()
{
// Commentted hy '//' only allowed within function
$this
->
foo
=
'foo'
;
# Commentted by '#' is not allowed within function
$this
->
foo
=
'bar'
;
}
}
复制代码
2. A docblock must contain a short description and minimum one parameter. Optionally a long description and multiple parameters can be added.
For example :
/**
* One short description and one parameter at least
*
* @param
*/
/**
* Long description and multiple parameters below
*
* One empty line to seperate the
* SHORT_DESCRIPTION,
* LONG_DESCRIPTION,
* PARAMETERS
*
* @param
* @todo
*/
复制代码
3. All docblock parts which are not keywords have to be under each other with the same indenting.
For example :
/**
* Right
*
* @component All descriptive parts
* @uses have the same indenting
*/
/**
* Wrong
*
* @component All descriptive parts
* @uses don't have the same indenting
*/
复制代码
4. Also when describing parameters the keywords, parameters, and description have to have the same indenting to be under each other.
For example :
/**
* Right, all descriptions are indented
*
* @param string $value Description of this value
* @param integer $othervalue Another description
*/
/**
* Wrong, not indenting
*
* @param string $value Description of this value
* @param integer $othervalue Another description
*/
复制代码
5. Each file which is delivered with the Zend Framework must have the following header block :
/**
* Zend Framework
*
* LICENSE
*
* This source file is subject to the new BSD license that is bundled
* with this package in the file LICENSE.txt.
* It is also available through the world-wide-web at this URL:
* [url]http://framework.zend.com/license/new-bsd[/url]
* If you did not receive a copy of the license and are unable to
* obtain it through the world-wide-web, please send an email
* to [[email protected]][email protected][/email] so we can send you a copy immediately.
*
* @category Zend
* @package __PACKAGENAME__
* @subpackage __SUBPACKAGENAME__
* @copyright Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. ([url]http://www.zend.com[/url])
* @license [url]http://framework.zend.com/license/new-bsd[/url] New BSD License
* @version $Id: $
* @depreciated Since 0.0.1
*/
复制代码
This format can be used in any project, for example :
/**
* Project name
*
* LICENSE
*
* License information
* in multiple lines (maybe)
*
* @category Category name
* @package Package of this file
* @subpackage Subpackage which include this file
* @copyright Copyright information
* @license License info for short
* @version $ Id and version description $
* @depreciated Since xxx
*/
复制代码
6. When other filestypes are used like *.SH, *.BAT, *.JS and so on, the header block must also be contained as header comment. Only when a filetype does not support comments like *.CSS the header block can be omited.
For example :
// zf.bat
REM Zend Framework
REM
REM LICENSE
REM
REM This source file is subject to the new BSD license that is bundled
REM with this package in the file LICENSE.txt.
REM It is also available through the world-wide-web at this URL:
REM
http://framework.zend.com/license/new-bsd
REM If you did not receive a copy of the license and are unable to
REM obtain it through the world-wide-web, please send an email
REM to
[email protected]
so we can send you a copy immediately.
REM
REM Zend
REM Copyright (c) 2005-2009 Zend Technologies USA Inc. ( http://www.zend.com )
REM
http://framework.zend.com/license/new-bsd New BSD License
// zf.sh
#############################################################################
# Zend Framework
#
# LICENSE
#
# This source file is subject to the new BSD license that is bundled
# with this package in the file LICENSE.txt.
# It is also available through the world-wide-web at this URL:
#
http://framework.zend.com/license/new-bsd
# If you did not receive a copy of the license and are unable to
# obtain it through the world-wide-web, please send an email
# to
[email protected]
so we can send you a copy immediately.
#
# Zend
# Copyright (c) 2005-2009 Zend Technologies USA Inc. ( http://www.zend.com )
#
http://framework.zend.com/license/new-bsd New BSD License
#############################################################################
// *.js
The same with php files.
7. The @package clause has to be the component which this file is part of it, there must exist exact one @package clause per header.
For example :
/**
* ...
*
* @package Zend_Controller
* @subpackage ...
* @copyright ...
* @license ...
*/
abstract class
Zend_Controller_Router_Route_Abstract
implements
Zend_Controller_Router_Route_Interface
{
// ...
}
复制代码
Another example :
/**
* ...
*
* @package Zend_Db
* @subpackage ...
* @copyright ...
* @license ...
*/
class
Zend_Db_Adapter_Mysqli
extends
Zend_Db_Adapter_Abstract
{
// ...
}
复制代码
8. The @subpackage clause has to be a logical separation within this component. Logical separations occur when there are several directories which seperate parts of the same component. Only files which are in the main directory of the framework which is "Zend" can omit the subpackage. There must exist maximum one @subpackage clause per header.
First example :
/**
* @category ...
* @package ...
* @subpackage Adapter
* @copyright ...
* @license ...
*/
class
Zend_Db_Adapter_Mysqli
extends
Zend_Db_Adapter_Abstract
{
// ...
}
复制代码
Second example :
/**
* @category ...
* @package ...
* @subpackage Table
* @copyright ...
* @license ...
*/
class
Zend_Db_Table_Select
extends
Zend_Db_Select
{
// ...
}
复制代码
Third example for no subpackage :
/**
* @category Zend
* @package Zend_Auth
* @copyright ...
* @license ...
*/
class
Zend_Auth
{
// ...
}
复制代码
9. The @copyright clause has to include the actual year of the release of the framework.
For example :
/**
* @category ...
* @package ...
* @copyright Copyright (c) 2005-2008 Zend ...
* @license ...
*/
class
Zend_Acl
{
// ...
}
复制代码
10. If this file contains a depreciated class it must have the optional @depreciated clause.
For example :
/**
* ...
*
* @depreciated Since 1.1.1
*/
class depreciateMe
{
}
复制代码
11. All classes/files which are required must contain a @see clause.
For example :
/**
* @see Zend_Controller_Dispatcher_Interface
*/
require_once
'Zend/Controller/Dispatcher/Interface.php'
;
复制代码
12. A class or interface in Zend Framework must have a class header which clauses must be added in the below seen order :
/**
* Description of the class
*
* More descriptive text which
* is allowed to span multiple lines
*
* @category Zend
* @package __PACKAGE__
* @subpackage __SUBPACKAGE__
* @uses __USES__
* @see __SEE__
* @since __SINCE__
* @copyright Copyright (c) 2005-__ENDDATE__ Zend Technologies USA Inc. ([url]http://www.zend.com[/url])
* @license [url]http://framework.zend.com/license/new-bsd[/url] New BSD License
* @depreciated Since 0.0.1
*/
class
Zend_Controller_Dispatcher
extends
Zend_Controller_Dispatcher_Class
implements
Zend_Controller_Dispatcher_Interface
复制代码
13. The @uses clause in header has to contain the extended or implemented classname. When multiple classes or interfaces are used, you must include a @uses clause for every class or interface. When no class is extended or interface is implemented then the @uses clause must be ommitted.
For example :
/**
* ...
*
* @uses ArrayAccess
* @uses Iterator
* @uses Countable
* @package ...
* @copyright ...
* @license ...
*/
class
Zend_Dojo_Data
implements
ArrayAccess
,
Iterator
,
Countable
{
// ...
}
复制代码
14. The @see clause in header is optional and can be added to link to another component within the framework. You can add multiple clauses.
For example :
/**
* ...
*
* @see Zend_Parent
* @see Zend_Interface
* @package ...
* @copyright ...
* @license ...
*/
class
Zend_Class
extends
Zend_Parent
implements
Zend_Interface
{
// ...
}
复制代码
15. The @since clause can be added optionally to include the version since which this class is available. It must include the complete version number of the framework. Only one since clause is allowed to be added.
For example :
/**
* ...
*
* @category ...
* @package ...
* @copyright ...
* @license ...
* @since Class available since Release 0.6.0
*
* @todo ...
*/
class
Zend_Console_Getopt
{
// ...
}
复制代码
16. Each function must have a function header.
For example :
class
Zend_Foo
{
/**
* Full text description of this function.
* It described all possible things
* but should not extend the line length of 100 characters.
*
* @param boolean $value Value for checking
* @since Version 1.2.3
* @see Zend_Anything
* @throws Zend_Exception When value is false
* @return array
*/
public function
bar
(
$value
)
{
require_once(
'Zend/Anything.php'
);
if (
$value
) {
return array(
'foo'
=>
$value
);
} else {
throw new
Zend_Exception
(
'Throw me !'
);
}
}
}
复制代码
17. All parameters of the function must be available. The types allowed are listed here :
(a) boolean
(b) integer
(c) string
(d) float
(e) array
(f) false
(g) true
(h) null
(i) Zend_Xxx (must be an existing class of the framework)
18. If more than one type could be used then the possible types have to be seperated with "|" like show above.
For example :
/**
* @param array|null $config configurations
*/
复制代码
19. If a parameter can be omitted the description must prepend a (optional) to the description.
For example :
/**
* @param array|null $config (optional) My optional value
*/
复制代码
20. If the function can throw an exception the @throws clause must be declared. Multiple exception types must be seperated with “|”. Also a description must be added why the exception is thrown.
For example :
class
Zend_XmlRpc_Server
extends
Zend_Server_Abstract
{
/**
* Handle an xmlrpc call (actual work)
*
* @param Zend_XmlRpc_Request $request
* @return Zend_XmlRpc_Response
* @throws Zend_XmlRpcServer_Exception|Exception
* Zend_XmlRpcServer_Exceptions are thrown for internal errors; otherwise,
* any other exception may be thrown by the callback
*/
protected function
_handle
(
Zend_XmlRpc_Request $request
)
{
// ...
}
}
复制代码
21. A @return clause must always be defined. Only for class constructor and destructor the @return clause must be ommitted. If multiple types can be returned the types must be seperated with "|". An description can be appended, but is not necessary.
For example :
class
Zend_Form
implements
Iterator
,
Countable
,
Zend_Validate_Interface
{
/**
* Overloading: access to elements, form groups, and display groups
*
* @param string $name
* @return Zend_Form_Element|Zend_Form|null
*/
public function
__get
(
$name
)
{
// ...
}
}
复制代码
22. If the class itself is returned (fluid interface) then the description ”Provides a fluent interface“ must be added.
For example :
class
Zend_Auth
{
/**
* Sets the persistent storage handler
*
* @param Zend_Auth_Storage_Interface $storage
* @return Zend_Auth Provides a fluent interface
*/
public function
setStorage
(
Zend_Auth_Storage_Interface $storage
)
{
$this
->
_storage
=
$storage
;
return
$this
;
}
}
复制代码
23. If the function does not return any value then the return value must be set to "void".
For example :
class
Zend_Application
{
/**
* Run the application
*
* @return void
*/
public function
run
()
{
$this
->
getBootstrap
()->
run
();
}
}
复制代码
24. Keep in mind that the "void" and "null" are not the same. Null means that a empty variable is returned. But void means that nothing is returned. This is a small but important difference. Therefor when return is even not called, void has to be declared in the function docblock.
For example :
class
Zend_Class
{
/**
* @return void
*/
public function
returnTheVoid
()
{
// Return nothing
}
/**
* @return null
*/
public function
returnTheNull
()
{
return
null
;
}
}
复制代码
.
