Ve větších projektech nám už přestávají klasické komentáře stačit. Potřebujeme si poznačit, kde se která třída/funkce nachází, který skript vypisuje kterou část, kde co includujeme… V tomto případě je na čase napsat programátorskou příručku. Nebo doufat, že si za půl roku vzpomeneme, co jsme to vlastně dělali 

V našem případě raději využijeme programátorskou příručku. Jistě se nikomu po náročném projektu nechce trávit čas při psaní několika stránek dokumentace. Pro tento způsob má PHP hned několik řešení. Nejznámější způsob dokumentace je pomocí [b]phpDocumentor[/b]. Vychází ze známého JavaDoc, který znají jistě všichni, kteří přišli s Java do styku. Je asi jasné, že JavaDoc se používá na dokumentaci v programovacím jazyku Java. Stejně jako v Java, dokumentace se tvoří pomocí [b]/** ….popis… */ [/b]. Více si probereme v další díle, nyní jen kratičkou ukázku:


<?php

	/**

	 * OBSLUHA_MYSQL

	 * 

	 * muj projekt

	 * @author Jan Novák

	 * @version 1.0 - 2007

	 * @package Tridy

	 */



	

	/**

	 * trida pro pripojeni k databazi

	 */

	class MySQL {

		

		/**

	       * link na pripojeni k db

	       * @access private

     	       * @var objekt

	       */

		private $link;

		/**

		 * provede MySQL dotaz

		 * @param $query dotaz_pro_MySQL

		 * @return integer Mysql_result 

		 */

		public function query($query) { 

                  ... 

                  ...

                }

       }

Co to teda ten phpDocumentor je?

Je to nástroj pro automatickou tvorbu dokumentace [b]přímo z kódu[/b] našeho projektu. Je napsán v php a může být použit i z příkazové řádky. Webové rozhraní je samozřejmostí. Jedna z nejdůležitějších vlastností u tohoto programu je export. Naštěstí je phpDocumentor už ve verzi 1.4.0, takže o export se tvůrci náležitě postarali. Máme na výběr mezi XML, CHM (nápověda Windows), PDF a taky HTML a to včetně velkého množství šablon.

phpDocumentor s IDE

Každý má své oblíbené IDE ( rozuměj vývojové prostředí ). Nejznámější je asi PSPad, který už dlouhá léta tvoří jeden český programátor v Delphi. Tento program se hodí na menší projekty. Ptáte se, proč pletu IDE a phpDocumentor dohromady? Podívejte se na obrázek.

Jak můžete vidět, některá vývojová prostředí umí, krom napovídání tagů, již vytvořenou dokumentaci přímo používat. Všimněte si, jak vzorový kód odpovídá podtrženému na obrázku. Ano, pro autora projektu je to pomoc menší, ale představte si, že projekt pro vás někdo přebírá. Případně se po delší době ke kódu vracíte. Ukázkový obrázek je z vývojového prostředí [b]Eclipse[b/], které je známé především pro programátory Java. Nicméně existuje i mutace pro PHP. Upozorňuji, že Eclipse je naprogramován v Java, čili čekejte zvýšené hardwarové nároky. Každopádně pokud máte dost paměti...

Pro tento díl, to bude vše. Doufám, že vás phpDocumentor zaujal. V dalších dílech se podíváme na základní tvorbu dokumentace a později se taky dostaneme i k návodu na vytvoření dokumentace.