Présentation de pdoc (rc1)

J’en avais un peu marre de ces générateurs de documentation qui obligent à utiliser des syntaxes bizarres, et qui obligent à utiliser une certaine forme de commentaire, au lieu de dire « tout commentaire qui précède un espace de nom, une classe, une méthode, un attribut ou une fonction est sa documentation ». Après tout, s’il y a un commentaire, c’est que c’est utile.

De l’autre côté il y a rdoc pour ruby : simple, efficace et on rédige sa doc de manière naturelle, en écrivant un texte avec des paragraphes, des listes et des blocs de code.

J’ai (un peu) cherché un équivalent pour PHP, mais je n’ai rien trouvé. La plupart sont des clones de doxygen — et vous aurez compris que je n’aime pas doxygen. La configuration est une horreur, et la documentation est chiante à rédiger.

Comme le moto de tout bon linuxien qui se respecte c’est « si ça existe pas code-le » et qu’on n’est jamais mieux servis que par soi-même, voici pdoc (télécharger). Il est plutôt basique et le code est un poil crade, mais il marche et génère de la doc comme je l’aime. Vous pouvez voir par exemple la documentation de Misago (un autre de mes projets PHP).

Et pour finir un exemple :

# This is a comment for the following class.
#
# = This is a heading
#
# This is a
# paragraph.
#
#
# == This is sub-heading
# 
# - this is a list (first item)
# - (second item)
#
class MyClass
{
  # Comments `$var`.
  public $var;

  # This comment is discarded.

  # This is the long comment for +MyClass::my_method()+.
  # You may fill it with a lot of things.
  # 
  # `$toto` can be:
  # 
  # - something
  # - something else
  # 
  # == Example:
  # 
  #   $c = new MyClass();
  #   $c->my_method('my_var');
  # 
  # See http://some.url/ for more details.
  function my_method($toto)
  {
    
  }
  
  # @private
  function undocumented_public_method()
  {
    
  }
}

Laisser un commentaire

Entrez vos coordonnées ci-dessous ou cliquez sur une icône pour vous connecter:

Logo WordPress.com

Vous commentez à l'aide de votre compte WordPress.com. Déconnexion / Changer )

Image Twitter

Vous commentez à l'aide de votre compte Twitter. Déconnexion / Changer )

Photo Facebook

Vous commentez à l'aide de votre compte Facebook. Déconnexion / Changer )

Photo Google+

Vous commentez à l'aide de votre compte Google+. Déconnexion / Changer )

Connexion à %s


%d blogueurs aiment cette page :