Основи на phpDocumentor документацията в PHP

1.Въведение
2.Основи на php документацията
3.Документиране на php елементите
4.Елементите(таговете) предоставени ни от phpDocumentor

Въведение

Добрата документация е ключът към успеха на какъвто и да е софтуерен проект. Дори понякога качеството на документацията може да е по-важна от качеството на самия код.
Когато е пишем трябва да се съобразяваме за кого е пишем. Там където софтуера е само за използване и единствено програмистите имат достъп до него, какъвто е и софтуера на Майкрософт, ще трябва да наблегнем върху писането на добра документация за крайния потребител.

Какво иска крайния потребител?

Писане в стила на инструкции, които обясняват и описват как определена променлива е използвана.
Информация за интерфейса, никакви детайли от ниско ниво.
Примери как да го използват и материал, чрез който да се обучат.

При писането за проекти от вида „отворен код”, трябва да знаем, че проекта ще бъде достъпен и преглеждан от повече хора. Той ще расте, разширява и поправя откривайки бъгове в него.

Какво иска програмиста ?

Детайли относно взаимодействието между програмните елементи, с кои елементи какво се случа.
Къде в сорс-кодът настъпват действия или серия от действията.
Как може да разширим кодът при нужда от добавяне на нова функционалност.


Употребата на phpDocumentor определено ще подобри видът и усещането на вашата документация, ще ви помогне да създадете динамична документи, които лесно се поддържат и винаги ще са съвременни. Той ще ви осигури страхотна документация за вашите програми.

Какво е phpDocumentor?

PhpDocumentor, понякога наричан phpdoc или phpdocu, е текущ стандартен инструмент за автоматична документация на езикът PHP. Подобен на Javadoc, и писан на PHP, phpDocumentor може да бъде използван от командния ред или мрежовия интерфейс за да създаде професионална документация от вашия php сорс-код.


В тази статия ще разгледаме основите на phpDocumentor и ще обясним как да документираме качествено. Няма да се задълбочаваме. Повече информация може да намерите на http://www.phpdoc.org/

Основи на php документацията

Процеса на документиране започва с основния елемент, който изглежда по този начин:

CODE

1 2 3

/**  *  */

Внимавайте, защото ако има ред, който не започва с „*” ще бъде игнориран.

Документирането засяга кода, поставен веднага след него.

Пример :

CODE

1 2 3 4 5 6

/**  * Ако има разстояние след документния блок ..., ще се случи това, което не желаем  */  function foo()  {  }

В случая, който следва, коментара ще засегне функция която не трябва.

Пример :

CODE

1 2 3 4 5 6 7 8 9

/**  * Документен блок предназначен за foo?  *  * Но, това ще засегне функцията, която дефинира константата”me”.  */  define('me',2);  function foo($param = me)  {  }

Повече за блока с коментарите

Блока съдържа три основни елемента:

Кратко описание
Обширно описание
Етикети(тагове)

Краткото описание стой в началото на блока(започва от първия ред). То завършва с празен ред. Ако е по-дълго от три реда се взима само първия.
Обширното описание започва след празния ред. Размера му може да е толкова голям, колкото вие решите.

Пример :

CODE

1 2 3 4 5 6 7 8 9

/**  * Това е кратко описание  *  *  Това е обширно описание. Остава още само да посочим, че този описателен  *  и анализиращ метод дава също така основа за постигането на отделните  *  форми на душевния живот, различията на половете,  националните характери,  *  изобщо на главните типове цели в човешкия живот, а също така на типовете индивидуалности.  *  */

Описателни детайли в документните блокове

Използвате се няколко допълнителни и HTML тага, чрез които допълнително форматираме текста в блоковете. Без тях коментарите ще се извличат като обикновен текст.

Ето ги и тях:

<b> - одебилен текст
<code> - използувайте този таг за да обграждате PHP код. Кода ще се оцвети синтактично
<br> - указва нов ред
<i> - наклонен текст
<kbd> - обозначаваме вход от клавиатурата или изпращане на данни към дисплея
<li> - елемент на списък
<ol> - подреден списък
<p> - параграф
<pre> -- преформатиран текст
<samp> - описваме нещо, давайки го за пример
<ul> - неподреден списък
<var> - обозначаваме име на променлива


Пример :

CODE

1 2 3 4 5 6 7 8 9

/**  * Примерен блок със съдържание на код  *  * <code>  * /**  * * моя код  * {@*}  * </code>  */

PhpDocumentor разпознава също елементи от списъци, започващи с -,+,#,●  или какъвто и да е подреден списък с последователни числа или числа следвани от точка(.).  Разграничителя трябва да бъде следван от интервал(не табулация!) празните места трябва да са подредени точно, или phpDocumentor няма да разпознае елементите на списъкът, които са в него.

CODE

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15

/**  * Блок със списък  *  * Простичък списък:  * - елемент 1  * - елемент 2, също така  * може да съществува и на няколко реда  * - елемент 3  * това му е края. Следващия списък еподреден  * 1 подреден елемент 1  * 2 подреден елемент 2  * край. Този също е подреден:  * 1. подреден елемент 1  * 2. подреден елемент 2  */

PhpDocumentor поддържа шаблони, които ни помагат да намалим допълнително писане на коментари. Например, ако голям брой от променливите на клас са частни, ще използваме шаблон за да ги маркираме всички като такива.
Заглавната част на шаблон е различна от нормалната заглавна част. Този вид блок започва с 6 последователни знака(/**#@+), който са задължителни:

Пример :

CODE

1 2 3

/**#@+  *  */

Завършва със задължителните 8 знака(/**#@-*/), който са индикатор за край на шаблона.

Пример:

Документация с шаблон.

CODE

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21

class Bob  { // Начало на шаблона /**#@+  * @access private  * @var string  */  var $_var1 = 'променлива 1';  var $_var2 = 'променлива 2';  var $_var3 = 'променлива 3';  var $_var4 = 'променлива 4';  var $_var5 = 'променлива 5';  var $_var6 = 'променлива 6';  var $_var7 = 'променлива 7'; /**  * Две думи  */  var $_var8 = 'Две думи'; /**#@-*/  var $publicvar = 'Публична променлива';  }

Документация без използването на шаблон.

Етикети (тагове)

Етикетите са думи, които започват с префикса "@". Етикетите информират phpDocumentor как да представя или променя документацията. Те не са задължителни, но ако вие използувате етикети, трябва да спазвате техните специфични изисквания за да се анализират правилно.

Това е списък с основните тагове предоставени ни от phpDocumentor:

CODE

1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40

/**  * Кратко описание  *  * Обширно описание......................................  *  * @abstract  * @access публичен или частен  * @author име на автора <електронен@адрес>  * @copyright права  * @deprecated описание  * @deprec псевдоним на deprecated  * @example /път/до/примера  * @exception Javadoc-съвместимост,където е необходимо  * @global type $globalvarname  или  * @global type Описание на глобална променлива използвана във функция  * @ignore  * @internal частна информация достъпна единствено от разработчиците  * @param type [$varname] описание  * @return type описание  * @link URL адрес  * @name псевдоним  или  * @name $globalvaralias  * @magic phpdoc.de съвместимост  * @package име на пакет  * @see име на елемент, към който може да се обърнем за повече информация  * @since версия или дата  * @static  * @staticvar type описваме употребата на статична променлива, съдържана от функция  * @subpackage дъщерен пакет  * @throws Javadoc-съвместимост, където е нужно  * @todo phpdoc.de съвместимост  * @var type тип на променлива  * @version version  */  function my_function()  {  ...  }