Code-Dokumentation

10/09/2009 - 11:47 von Ole Streicher | Report spam
Hallo,

auch diese Frage ist vermutlich trivial und 1000x beantwortet; aber
zumindest in meinem Buch (Nutshell) auf der Python-Doku-Seite habe ich
nichts gefunden: Wie dokumentiere ich sinnvollerweise den Code (API)?

Soweit bin ich:

class MyClass:
"""Kurzbeschreibung der Klasse.

Langbeschreibung.

Class Attributes:
a1 -- erstes Attribut (vom Typ xyz)

Object Attributes:
a2 -- zweites Attribut (vom Typ def)

"""
def my_func(x):
"""Kurzbeschreibung.

Langbeschreibung.

Parameters:
x -- ein Parameter (vom Typ xxx)

Return:
etwas vom Typ yyy

"""

Ich vermute aber, dass es für all diese Punkte (Attribute, Parameter,
Rückgabewerte, Typen) formalere Beschreibungen gibt, die z.B. auch
automatisiert testbar sind, und dass auch die Überschriften einem
gewissen Standard genügen.

Viele Grüße

Ole
 

Lesen sie die antworten

#1 Torsten Bronger
10/09/2009 - 12:02 | Warnen spam
Hallöchen!

Ole Streicher schreibt:

auch diese Frage ist vermutlich trivial und 1000x beantwortet;
aber zumindest in meinem Buch (Nutshell) auf der Python-Doku-Seite
habe ich nichts gefunden: Wie dokumentiere ich sinnvollerweise den
Code (API)?



Einen de-facto-Standard gibt es nicht, aber reStructuredText in
irgendeiner Form wird sehr oft benutzt, und ich glaube auch von
höchster Stelle empfohlen. Ich benutze reStructuredText in der
Epydoc-Variante.

Wobei dabei nicht der Eindruck aufkommen sollte, daß seien wilde
Dialekte von reStructuredText. Vielmehr ist reStructuredText bewußt
so spezifiziert, daß man es für verschiedene Zwecke erweitern (und
natürlich auch einschrànken) kann.

Tschö,
Torsten.

Torsten Bronger, aquisgrana, europa vetus
Jabber-ID:
oder http://bronger-jmp.appspot.com
http://www.dubistterrorist.de/

Ähnliche fragen