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.