PHPDOC template
Templates used when documenting JANUS
File dockblock
/**
* [CLASS SHORT DESCRIPTION]
*
* PHP version 5
*
* JANUS is free software: you can redistribute it and/or modify it under the
* terms of the GNU Lesser General Public License as published by the Free
* Software Foundation, either version 3 of the License, or (at your option)
* any later version.
*
* JANUS is distributed in the hope that it will be useful, but WITHOUT ANY
* WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
* FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more
* details.
*
* You should have received a copy of the GNU Lesser General Public License
* along with JANUS. If not, see <http://www.gnu.org/licenses/>.
*
* @category SimpleSAMLphp
* @package JANUS
* @subpackage [SUBPACKAGE NAME]
* @author Jacob Christiansen <jach@wayf.dk>
* @copyright 2009 Jacob Christiansen
* @license http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
* @version SVN: $Id$
* @link http://code.google.com/p/janus-ssp/
* @see [INTERNAL REFERENCE]
* @since File available since Release [RELEASE VERSION]
* @deprecated File deprecated in Release [RELEASE VERSION]
* @todo [TODO ITEM]
*/
Class dockblock
/**
* [CLASS SHORT DESCRIPTION]
*
* [CLASS LONG DESCRIPTION]
*
* @category SimpleSAMLphp
* @package JANUS
* @subpackage [SUBPACKAGE NAME]
* @author Jacob Christiansen <jach@wayf.dk>
* @copyright 2009 Jacob Christiansen
* @license http://www.gnu.org/licenses/lgpl.html GNU Lesser General Public License
* @version SVN: $Id$
* @link http://code.google.com/p/janus-ssp/
* @see [INTERNAL REFERENCE]
* @since Class available since Release [RELEASE VERSION]
* @deprecated Class deprecated in Release [RELEASE VERSION]
* @todo [TODO ITEM]
*/
Use @subpackage name: "Core" for basic JANUS stuff or "AuthenticationSource", "ProcessingFilter", "Hooks", ...
Remember to fill out the @since. For most functionality this is "1.0.0"
Class methods dockblock
/**
* [FUNCTION SHORT DESCRIPTION]
*
* [FUNCTION LONG DESCRIPTION]
*
* @param [TYPE] [PARAMETERNAME] [DESCRIPTION]
*
* @return [TYPE] [DESCRIPTION]
* @throws [EXCEPTION TYPE] [DESCRIPTION]
* @link [EXTERNAL REFERENCE]
* @see [INTERNAL REFERENCE]
* @since Method available since Release [RELEASE VERSION]
* @deprecated Method deprecated in Release [RELEASE VERSION]
* @todo [TODO ITEM]
*/
You can put an @author tag in the docblock for a class method, if the author of the method is different from the class author, but this is NOT recommended.
It is RECOMMENDED to put another @author tag in the docblock for the class instead.
Class property dockblock
/**
* [PROPERTY SHORT DESCRIPTION
*
* [PROPERTY LONG DESCRIPTION]
*
* @var [TYPE] [DESCRIPTION]
* @link [EXTERNAL REFERENCE]
* @see [INTERNAL REFERENCE]
* @todo [TODO ITEM]
*/
Functions dockblock
/**
* [FUNCTION SHORT DESCRIPTION]
*
* [FUNCTION LONG DESCRIPTION]
*
* @param [TYPE] [PARAMETERNAME] [DESCRIPTION]
*
* @return [TYPE] [DESCRIPTION]
* @throws [EXCEPTION TYPE] [DESCRIPTION]
*
* @link [EXTERNAL REFERENCE]
* @see [INTERNAL REFERENCE]
* @since Function available since Release [RELEASE VERSION]
* @deprecated Function deprecated in Release [RELEASE VERSION]
* @todo [TODO ITEM]
*/
Put @author tags in the FILE docblock to document authors of function, NOT in the function dockblock.