Discussion :

[Benjamin Delespierre]

Bonjour à tous.

Je suis sur un projet pour PHP 5.3 utilisant les classe et les namespaces. J'aurais bien besoin de vos lumières et retrours d'expérience concernant le formalisme Doxygen pour la génération de documentation.

Plus particulièrement, j'aurais besoin de précisions sur
- @namespace
- @package
- @subpackage
- @abstract et @interface
- @since et @version

Comment formalisez vous votre code ? Comment formatter au mieux ?

Voici le formalisme que j'utilise jusqu'ici:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
 
/**
 * <project name>
 * -----------------------------------------------------------------------------------------------------------------------------------------
 * @copyright <company>
 * @category Backoffices
 * @author B. Delespierre
 * @version <version>
 */
namespace <namespace>;
 
use \RuntimeException;
 
/**
 * Default autoloader
 *
 * TODO add autoloader description & usage
 *
 * @author Delespierre
 * @version 1.0.0
 * @package <package>
 */
final class Autoloader extends Object {

Am I doing it right ?

[grunk]

Plus particulièrement, j'aurais besoin de précisions sur
- @namespace
- @package
- @subpackage
- @abstract et @interface
- @since et @version

@namespace me semble assez explicite , tu indique ici le namespace utilisé
@package et @subpackage sont un peu plus obscure. Dans mon framework je m'en sert de la manière suivante :

J'ai par exemple un dossier Form qui contient des classe de formulaire

@package Form

Dans ce dossier j'ai des classes et un sous dossier Elements
Les classes dans Elements aurons donc

@package Form
@subpackage Element

Et si j'ai encore des sous dossier:

@package Form
@subpackage Element/sousdossier/soussous/

@abstract et @interface sont à utilisé dans le cas d'une classe abstraite ou d'une interface

@since je l'utilise quand je rajoute une méthode , plus tard dans le code , je fait un truc du genre

@since 1.0.1

en spécifiant la version depuis laquelle elle est dispo

[Benjamin Delespierre]

Je vois. J'avais déjà eu un aperçu de ton formalisme quand tu m'a passé des exemples de classes tirées de ton composant

En ce qui concerne @namespace, @package et @subpackage, quel est le formalise à utiliser ? / ou \ ou autre chose ?
En fait j'ai du mal à discerner la notion de package quand on a par exemple un namespace qui ressemble à:

Code :

Sélectionner tout - Visualiser dans une fenêtre à part

namespace composant\data\source\mysql\reflector\adapter;

[grunk]

Je me rend compte que j'ai dis une connerie pour package et subpackage , les seuls caractères spéciaux autorisés sont -_[].

Voir la doc phpdoc pour tous les détails :
http://manual.phpdoc.org/HTMLSmartyC...ckage.pkg.html

[Benjamin Delespierre]

Alright. Merci pour la doc.

Je ferme le sujet.