Php – Commenter pour netbeans

De puis peu (poke @makemereach ^^), j’utilise netbeans pour mes développements php (perso et pro). Et cela pour plusieurs raisons: support de svn, transfert/synchro ftp et sftp… Ce n’est sûrement pas le seul IDE de dév php qui existe, et je suppose que cela pourrait faire l’objet d’un long débat. Ce n’est pas l’idée de cet article ^^ (même si je suis très curieux de connaître vos IDE :) ).

En utilisant netbeans, je me suis aperçu que la classe facebook était reconnue par netbeans : l’ide suggérait de l’autocomplétion, et affichait de la doc lorsque j’appelais des méthodes propres à la classe. D’où mon interrogation à ce moment: mais comment-se-fait-ce(book) ??

En ouvrant la classe facebook (fournie par facebook hein), j’ai constaté qu’elle était commentée d’une manière particulière. Voyons donc la façon dont ces commentaires sont rédigés…

L’idée de base est que chaque commentaire est précédé par

/**

Tournure de commentaire presque classique avec les /* et les */, mais notez bien les 2 étoiles ** après le /. Netbeans l’interprète comme un commentaire de classe.

Ainsi :
/**
* Class maClasse
* Description de la classe
*/

Vous permettra d’avoir de l’autocompletion sur
new maClasse()

Mieux encore :

/**
* Simple constructor
* @param string $arg Argument de type string
*/
public function __construct($arg){}

Vous permettra même de préciser à netbeans les arguments attendus, et leur type, tout en spécifiant l’utilité de la méthode. Imaginons un :

/**
* Récupère un article à partir de son id.
* @param int $articleId Id de l'article à récupérer.
*/
public function getArticle($articleId){
}

Netbeans vous expliquera que $articleId est un integer, ainsi que ce à quoi il correspond. Et mine de rien, pour les collègues qui passent derrière, c’est bien pratique.

De la même façon, on peut spécifier le type de ce qui est retourné par la méthode.

/**
* Récupère un article à partir de son id.
* @param int $articleId Id de l'article à récupérer.
* @return object Un objet de type article
*/
public function getArticle($articleId){
      ....
      return $article;
}

Et tout ça vous sera retourné, mis en forme, par Netbeans.

Je ne sais pas si cette syntaxe est reconnue par tous les IDE, mais vu que facebook a commenté sa classe de cette manière, cela me semble fort probable…