In-Portal Developers Guide

This is a wiki-based Developers Guide for In-Portal Open Source CMS. The purpose of this guide is to provide advanced users, web developers and programmers with documentation on how to expand, customize and improve the functionality and the code the In-Portal software. Please consider contributing to our documentation writing effort.

K4:Сопутствующая документация

From In-Portal Developers Guide

Jump to: navigation, search

Alex (Talk)
(категория, дополнение)
Next diff →

Revision as of 12:42, 6 September 2008

Стандарты в программировании Стандарты в программировании
Статьи в этой категории

Contents

Формат документации

Все блоки с документацией должны быть совместимыми с форматом, используемом в phpDocumentor. Описание phpDocumentor формата не является целью этой статьи. За более подробной информацией посетите http://phpdoc.org/. Во всех файлах, в которых находиться PHP код самого K4 или код его использующий, сверху должен находиться "file-level" блок документации. Над каждым классом следует писать "class-level" блок документации. Ниже приведены примеры подобных блоков.

Файлы

Каждый файл в котором находиться PHP код должен вверху содержать блок документации состоящий как минимум из ниже приведённых тэгов формата phpDocumentor:

/**
 * Short description for file
 *
 * Long description for file (if any)...
 *
 * @copyright  2008 Intechnic Corporation
 * @license    http://www.intechnic.com/license.txt
 * @version    $Id:$
*/

Классы

Каждый класс должен вверху содержать блок документации состоящий как минимум из ниже приведённых тэгов формата phpDocumentor:

/**
 * Short description for class
 *
 * Long description for class (if any)...
 *
 * @copyright  2008 Intechnic Corporation
 * @license    http://www.intechnic.com/license.txt
 */

Функции

Каждая функция, включая методы объектов должна сопровождаться блоком документации со следующим содержанием:

  • описание;
  • список всех аргументов;
  • все возможные возвращаемые значения;
/**
 * Short description
 * 
 * Long description
 *
 * @param kEvent $event
 * @param int $mode can accept values hBEFORE or hAFTER
 * @return Array
 */

В приведённом выше примере показано, как можно описывать аргументы функций (тип значения, название, описание), а также её описание и тип возвращаемого значения. Если функция является событием в обработчике событий то:

  • если событие это hook, то нужно написать "[HOOK] " перед его кратким описанием;
  • если событие вызывается в результате AJAX запроса, то нужно написать "[AJAX] " перед его кратким описанием.

Такие краткие дополнения к описанию события помогут понять где его применяют, если из названия события это не становиться ясным.

Image:Infobox Icon.gif В случае, когда используются ключевые слова "public", "private", или "protected" указывать "@access" в блоке документации не обязательно.