documentation pour un paquet en PHP?

Question

donc dans un dossier PayPal j'ai plusieurs classes pour utiliser leur API.

Je veux faire une documentation sur la façon d'utiliser toutes les classes de manière séquentielle. alors voici mes questions:

1. comment puis-je créer un paquet pour eux? cause au-dessus de chaque classe j'ai utilisé phpdoc tag @package PayPal. est un paquet en php juste un dossier? Où dois-je mettre la documentation pour le paquet?

2. il y a des meilleures pratiques pour cela? un fichier dans le dossier nommé ...?

3. comment mettre des exemples spécifiques à une classe ou à un paquet, par ex. étape 1 bla bla, étape 2 bla bla? merci!

Answer 1

Vous pouvez avoir les mêmes annotations de package pour plusieurs classes dans des fichiers distincts. PHP Documentor les collectera et lors de la création des API Docs, regroupera les fichiers avec la même annotation de paquet.

Par exemple http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate.php

/** 
* @category Zend 
* @package Zend_Validate 
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
* @license http://framework.zend.com/license/new-bsd  New BSD License 
*/ 
class Zend_Validate implements Zend_Validate_Interface 

et http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Alnum.php

/** 
* @category Zend 
* @package Zend_Validate 
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
* @license http://framework.zend.com/license/new-bsd  New BSD License 
*/ 
class Zend_Validate_Alnum extends Zend_Validate_Abstract 

Les deux sont des fichiers séparés, mais appartiennent à l'ensemble Zend_Validate. Ainsi, sur http://framework.zend.com/apidoc/core/, vous pouvez les trouver regroupés dans le même paquet.

Vous pouvez également avoir des sous-packages pour regrouper des classes supplémentaires en dessous d'un package normal. Par exemple http://framework.zend.com/svn/framework/standard/trunk/library/Zend/Validate/Sitemap/Lastmod.php

/** 
* Validates whether a given value is valid as a sitemap <lastmod> value 
* 
* @link  http://www.sitemaps.org/protocol.php Sitemaps XML format 
* 
* @category Zend 
* @package Zend_Validate 
* @subpackage Sitemap 
* @copyright Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com) 
* @license http://framework.zend.com/license/new-bsd  New BSD License 
*/ 
class Zend_Validate_Sitemap_Lastmod extends Zend_Validate_Abstract 

Voir la documentation de l'API lien ci-dessus pour voir comment il montre quand produit.

Vous ne documentez pas les annotations de package. L'annotation est juste utilisée pour grouper logiquement des classes ou des fichiers auxquels elles appartiennent conceptuellement. Si vous voulez avoir une description de paquet, écrivez-la dans le fichier le plus approprié du paquet ou créez un fichier séparé et donnez-lui la même annotation que les autres fichiers/classes de ce paquet.

Pour des exemples d'utilisation pour les packages, vous avez l'exemple d'annotation pour lier des fichiers contenant des exemples ou simplement les écrire en ligne avec des balises de code dans DocBlocks. Si vous utilisez un fichier séparé pour documenter vos paquets, vous pouvez les insérer là.

/** 
* MyLib 
* 
* Files under the MyLib package do foo and bar. They are baz. 
* 
* Usage Examples of MyLib classes 
* <code> 
* $foo = new Foo; 
* $foo->doSomething() 
* </code> 
* 
* @package MyLib 
* 
* @example /some/path/to/an/example/file 
*/