Kategorien
  • Erstsemester
  • Kommunikation

StudipCsDokumentation

Dokumentation

Coding Style Index?

Auf dieser Seite... (ausblenden)

  1.   1.  Kopf-Kommentare

1.  Kopf-Kommentare

Alle Quellcode-Dateien sollen einen „Page-level“ Docblock am Datei-Anfang besitzen und einen „Class-level“ Docblock unmittelbar vor jeder Klasse.

Beispiel:

  1. <?php
  2.  
  3. /* vim: set expandtab tabstop=4 shiftwidth=4 softtabstop=4: */
  4.  
  5. /**
  6. * Short description for file
  7. *
  8. * Long description for file (if any)...
  9. *
  10. * PHP versions 4 and 5
  11. *
  12. * LICENSE: This source file is subject to version 3.0 of the PHP license
  13. * that is available through the world-wide-web at the following URI:
  14. * http://www.php.net/license/3_0.txt.  If you did not receive a copy of
  15. * the PHP License and are unable to obtain it through the web, please
  16. * send a note to license@php.net so we can mail you a copy immediately.
  17. *
  18. * @category   CategoryName
  19. * @package    PackageName
  20. * @author     Original Author <author@example.com>
  21. * @author     Another Author <another@example.com>
  22. * @copyright  1997-2005 The PHP Group
  23. * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  24. * @version    CVS: $Id:$
  25. * @link       http://pear.php.net/package/PackageName
  26. * @see        NetOther, Net_Sample::Net_Sample()
  27. * @since      File available since Release 1.2.0
  28. * @deprecated File deprecated in Release 2.0.0
  29. */
  30.  
  31. /*
  32. * Place includes, constant defines and $_GLOBAL settings here.
  33. * Make sure they have appropriate docblocks to avoid phpDocumentor
  34. * construing they are documented by the page-level docblock.
  35. */
  36.  
  37. /**
  38. * Short description for class
  39. *
  40. * Long description for class (if any)...
  41. *
  42. * @category   CategoryName
  43. * @package    PackageName
  44. * @author     Original Author <author@example.com>
  45. * @author     Another Author <another@example.com>
  46. * @copyright  1997-2005 The PHP Group
  47. * @license    http://www.php.net/license/3_0.txt  PHP License 3.0
  48. * @version    Release: @package_version@
  49. * @link       http://pear.php.net/package/PackageName
  50. * @see        NetOther, Net_Sample::Net_Sample()
  51. * @since      Class available since Release 1.2.0
  52. * @deprecated Class deprecated in Release 2.0.0
  53. */
  54. class Foo_Bar
  55. {
  56. }
  57.  
  58. ?>
[Code herunterladen]

Kurzbeschriebung

Die Kurzbeschreibung muss in allen Docblocks existieren. Sie umfasst einen Satz, und sollten keinesfalls nur aus dem Namen des beschreibenden Objektes stehen.

PHP Version

Folgende Zeile muss in den Page-level-Docblock eingefügt werden. Sie beschreibt, unter welcher PHP-Version der Quellcode läuft:

  • PHP version 4
  • PHP version 5
  • PHP versions 4 and 5

@license

Sie können verschiedene Lizenzen für ihr Package verwenden. Sie müssen eine auswählen und diese sowohl im Page-level-, wie auch dem Class-level-Docblock einfügen:

@link

Die Link-Angabe muss im Page-level- and Class-level-Docblock erfolgen. Sie müssen den Eintrag für „PackageName“ natürlich durch den Namen Ihres Packages ersetzen. Auf diese Weise ist sicher gestellt, dass die API-Dokumentation die Links auf die Package-Homepage enthält.

@author

Es gibt keine klare Regel, wann jemand zur Liste der Quellcode-Autoren hinzugefügt werden sollte. Allgemein sollten sie substanziell beigetragen haben, ca. 10% bis 20% des Codes. Sie können Ausnahmen machen, wenn Methoden neu geschrieben wurden oder neue Logik beigesteuert wurde.

Einfache Code-Neuformatierungen oder Bug-Fixes sollten nicht zur Aufnahme in die Liste führen.

@since

Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nach dem ersten Release zum Package ergänzt wurde. Verwenden Sie es nicht beim ersten Release.

@deprecated

Dieses Tag ist erforderlich, wenn eine Datei oder Klasse nicht mehr benutzt wird, aber für die Rückwärtskompatibilität noch verfügbar ist.

@copyright

Sie können dieses Tag setzen, wenn Sie Copyright-Anmerkungen ergänzen wollen. Das Format des Tags: Die vierstellige Jahreszahl bzw. bei mehreren Jahren, nur das erste und letzte Jahr getrennt mit einem Querstrich; danach der Copyright-Inhaber, also die betreffenden Personen, Firma oder z.B. die PHP Group.

Beispiele:

  • @copyright 2003 John Doe and Jennifer Buck
  • @copyright 2001-2004 John Doe
  • @copyright 1997-2004 The PHP Group
  • @copyright 2001-2004 XYZ Corporation

License Summary

If you are using the PHP License, use the summary text provided above. If another license is being used, please remove the PHP License summary. Feel free to substitute it with text appropriate to your license, though to keep things easy to locate, please preface the text with LICENSE: .

@see

Fügen Sie ein @see-Tag hinzu, wenn Sie auf andere Abschnitte in der Package-Dokumentation verweisen. Wenn Sie mehrere Einträge hinzufügen, verwenden Sie nicht mehrere Tags, sondern trennen diese in einem Tag per Komma.

Abfolge und Leerzeichen

Um die langfristige Lesbarkeit zu gewährleisten, sollten Texte und Tags dem gegebenem Beispiel folgen. Diese Festlegungen entsprechen dem JavaDoc-Standard.

Verwendung von @package_version@

Es gibt zwei Wege @package_version@ zu ersetzen. Das ist abhängig davon, ob Sie die Package-Datei package.xml von Hand erzeugen oder das Package PackageFileManager benutzen.

Wenn Sie die Datei direkt bearbeiten, ergänzen Sie ein <replace>-Tag für jede Datei. Das XML sieht dann ähnlich wie dieses aus:

  1. <file name="Class.php">
  2.   <replace from="@package_version@" to="version" type="package-info" />
  3. </file>
[Code herunterladen]

Wenn PackageFileManager verwenden, rufen Sie addReplacement() für jede Datei auf:

  1. <?php
  2. $pkg->addReplacement('filename.php', 'package-info',
  3.                      '@package_version@', 'version');
  4. ?>
[Code herunterladen]

Letzte Änderung am August 22, 2008, at 10:07 PM von chueser. navigation & toc