[isf-wifidog] For developers: changes for new documentation

Benoit Grégoire bock at step.polymtl.ca
Mar 20 Déc 00:46:29 EST 2005


On December 19, 2005 08:24 pm, Max Horváth wrote:
> Hello developers,
>
> before commiting any changes to the CVS I'd like to inform you about
> what I changed and why I did it.

I agree with everything you propose save for the following:

> I added a new directory "docs". It contains a first version of a  
> PEAR::PhpDocumentor 1.3.0RC5 compilation.
> 
> We all know that WiFiDogs lacks regarding documentation. So I thought  
> now that almost no developers commits anything new to the CVS might  
> be the perfect moment to change a lot of files.
> 
> To get as less as possible errors and warnings regarding the  
> documentation compilation the first I had to change were the headers  
> of every PHP file.
> 
> The PHPdoc documentation will be very usefull for everyone. Right now  
> it just contains information for the developers, but we could and  
> should include information for the endusers (administrators of auth  
> servers) in it. But this will be a next step.

Our documentation-generation tool untill now has been doxygen.  I don't know 
how many attributes are conflicting with phpdocumentor, but I feel sharing 
the same tool for the C and PHP code has value. I'm open to switching if 
there is a compelling reason to do it.

> Next I ask you to translate every french PHPdoc into english. Later  
> I'd like to ask you to rename french function names, too - but that's  
> for later.

I'm already having huge difficulties making sure everyone writes strategic 
comments for EVERY function.  I am not about to pester people into 
translating comments in a language they may or may not master so well, 
especially while not every function has any comment yet.

Everyone knows that the recommended language for comments is now English, 
let's leave it at that.

Changing function names to english is fine as long as you are SURE you caught 
every instance of them.

Please remenber that any code in /lib, even if it's in the wifidog CVS is to 
be considered "externally maintained" and is off limits for stylistic type 
commits (except by the maintainer obviously).

I hope I'll come back to life after the new year.

-- 
Benoit Grégoire, http://benoitg.coeus.ca/
-------------- section suivante --------------
Une pièce jointe non texte a été nettoyée...
Nom: non disponible
Type: application/pgp-signature
Taille: 189 octets
Desc: non disponible
Url: http://listes.ilesansfil.org/pipermail/wifidog/attachments/20051220/10e3c841/attachment.pgp


More information about the WiFiDog mailing list