[Mapbender-dev] Documentation of methods at mapbender wiki

[Marc Jansen]

Hi list,

this surely is a good start!

Is this meant as a guideline to document the methods/functions/classes 
within the wiki/other written documentation or is it also meant to be 
used within the code itself?

I strongly favor documenting the code as well according to 
PHPDoc-standard, e.g.:

/**
 * Checks given email , and returns whether the passed email is a valid one
 *
 * @param string The email to test
 * @return boolean whether the given email mathces a certain syntax
 */
function isValidEmail($email) {
    
if(eregi("^[_a-z0-9-]+(\.[_a-z0-9-]+)*@[a-z0-9-]+(\.[a-z0-9-]+)*(\.[a-z]{2,3})$", 
$email)) {
        return true;
    }
    return false;
}


Marc






Toni Pignataro schrieb:
> !! for english version scroll below !!
>
> Hallo Liste,
>
> habe ein Beispiel für die Kommentierung von Methoden einer jeweiligen 
> Klasse angelegt.
> Auf der Seite 
> http://www.mapbender.org/index.php/Testdoc_Class_administration
> sind die Methoden:
>
> # 1.1 isValidEmail($email)
> # 1.2 sendEmail($fromAddr, $fromName, $toAddr, $toName, $subject, $body,
> &$error_msg )
> # 1.3 getRandomPassword()
> der Klasse "class_adminastration.php beispielhaft kommentiert.
>
> How to link:
> http://www.mapbender.org/index.php/How_to_doc_a_method
>
> Folgende Seiten bzw. Doks zur Auskommentierung habe ich dabei zum
> Vergleich herangezogen
>
> - 
> http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html#intro 
>
> - 
> http://www.professionelle-softwareentwicklung-mit-php5.de/erste_auflage/tools.code-documentation.phpdocumentor.html 
>
> - http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
>
> Bitte um Feedback bezüglich Inhalte oder Angaben welche bei der 
> Dokumentation von Methoden
> noch für euch nützlich sein könnten.
>
>
> Gruß,
> Toni Pignataro
>
>
> ENGLISH TRANSLATION
>
> Hello,
>
> I have posted same example for documenting methods of a class.
> The site http://www.mapbender.org/index.php/Testdoc_Class_administration
> shows an exemplified documentation of the methods:
>
> # 1.1 isValidEmail($email)
> # 1.2 sendEmail($fromAddr, $fromName, $toAddr, $toName, $subject, $body,
> &$error_msg )
> # 1.3 getRandomPassword()
> from the class_administration.php.
>
> Visit also:
> http://www.mapbender.org/index.php/How_to_doc_a_method
>
> For comparison of documenting methods I used following links:
>
> - 
> http://manual.phpdoc.org/HTMLSmartyConverter/default/phpDocumentor/tutorial_phpDocumentor.quickstart.pkg.html#intro 
>
> - 
> http://www.professionelle-softwareentwicklung-mit-php5.de/erste_auflage/tools.code-documentation.phpdocumentor.html 
>
> - http://java.sun.com/j2se/javadoc/writingdoccomments/index.html
>
> Please give some feedback about helpful topics or details for you, to
> use for documenting the methods.
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: dev-unsubscribe at mapbender.osgeo.org
> For additional commands, e-mail: dev-help at mapbender.osgeo.org
>


-- 

  ___________________________
  
  terrestris  GbR

    Marc Jansen
    Siemensstr. 8
    D-53121 Bonn


  T: ++49 (0)228 - 962 899 54
  F: ++49 (0)228 - 962 899 57 

  Email: jansen at terrestris.de
  Internet: www.terrestris.de
  ___________________________