Pfad in Initialisierung dokumentieren

[DMD-OS]

Hi Spezis
Ich habe zur Dokumentation mit Doxygen eine kleine Frage.
In meinem Code werden keine Variablen an die Klasse übergeben, aber innerhalb, welche erstellt.
Die erstellten Variablen bekomme ich aber nicht dokumentiert.

Code: Alles auswählen

import os


class Connectivity:
    """
    Beschreibung der Klasse 'Connectivity'
    """
    def __init__(self):
        """
        Initialisierung der benötigten Programmpfade.

        :type self.path_main: str
        :param self.path_main: Pfad des Programms

        :return:
        """
        self.path_main = os.getcwd()

Ich erhalte in Doxygen immer die Ausnahme:

Code: Alles auswählen

...warning: Member path_main (variable) of class Setup::Connectivity is not documented.

Wie macht mans richtig?
PS: Ich arbeite natürlich mit Python

[__blackjack__]

@DMD-OS: Attribute werden üblicherweise im Docstring der Klasse dokumentiert. Das in der `__init__()` ist ja auch falsch, weil Du da versuchst das als Argument zu dokumentieren, das ist ja aber gar kein Argument der `__init__()`. Ausserdem darf in Namen kein "." enthalten sein.

Da die `__init__()` grundsätzlich nichts zurück gibt, macht auch das ":return:" keinen Sinn.

[DMD-OS]

???

Code: Alles auswählen

import os


class Connectivity:
    """
    Beschreibung der Klasse 'Connectivity'
    """
    def __init__(self):
        """
        Initialisierung der benötigten Programmpfade.
        
        Attributes:
        path_main : str
            The X coordinate.
        """
        self.path_main = os.getcwd()

Das taucht zwar in der Docu auf, aber den Fehler gibt doxygen immer noch aus

[__deets__]

Docstring der Klasse ist der obere. Da gehört das hin.

[DMD-OS]

Was heißt das?

[__deets__]

Was blackjack doch auch schon schrieb. Doxygen erwartet die Dokumentation der Attribute auf KLASSENEBENE. Da legt man die in Python nicht an, aber du hast ja ein Tool gewählt, das von C++ stammt, und da ist das eben so.

[DMD-OS]

Immer noch nich

Code: Alles auswählen

class Connectivity:
    """
    Beschreibung der Klasse. Hier steht die genaue Beschreibung,
    wofür die Klasse da ist.
    Der Text genau also erstma noch n paar Zeilen weiter, bis 
    er aufhört.

    Attributes:
        :param path_main (str): Der Pfad des Programms
    """
    def __init__(self):
        """Initialisierung der benötigten Programmpfade."""
        self.path_main = os.getcwd()

in doxygen immer noch gleicher fehler, aber es ist jetzt in der verdammten klasse.

[__deets__]

Das ist ja auch kein param, oder? Hast du mal nach Beispielen in Python Projekten gesucht, die auch doxygen benutzen? Ist ja auf github nur eine Suche entfernt.

[__deets__]

Ich habe gerade mal versucht, die doxygen eigene Dokumentation auf dem iPhone zu lesen. Adaptiv ist die nicht. Ich würde den Entschluss überdenken.

[__blackjack__]

@__deets__: Wobei das auch bei Python oft auf Klassenebene dokumentiert wird, auch wenn die Attribute dort nicht angelegt werden. Die Frage ist da ob man zum Beispiel in einer Shell wenn man `help()` auf einem Objekt aufruft die Attribute auf dem Exemplar vor den Methoden beschrieben sehen möchte oder erst bei der `__init__()`-Methode.

[__deets__]

Finde ich auch voll ok. Ich denke trotzdem das es hier einiges an impedance-mismatch mehr gibt, als bei Sphinx, das in Python für Python gemacht ist.

[DMD-OS]

Ich dachte vorher, doxygen ist besser, weil man einfacher alles eingeben kann (ohne sich n Kopf zu machen)

[__blackjack__]

Dokumentation „ohne sich n Kopf zu machen“ geht mit keinem Dokumentationswerkzeug. Gute Dokumentation zu schreiben ist deutlich schwieriger als den Code zu schreiben.

Doxygen ist mal für C und C++ entwickelt worden und ist da ziemlich gut weil es so einiges an Information durch statische Analyze des Quelltextes herausziehen kann, was man dann nicht selbst eingeben muss. Der kann mittlerweile auch andere Programmiersprachen und bei Objective-C, Java, C# & Co, also statisch typisierten Programmiersprachen die sehr ähnliche Konzepte zu C und C++ haben funktioniert das auch prima. Andere Programmiersprachen wurden schon immer über Filter unterstützt die aus einem Quelltext ein C++-Gerüst gemacht haben was dann an Doxygen verfüttert wird. Und da fängt dann die Frage an wie gut man Konzepte aus einer Programmiersprache auf Konzepte aus C++ abbilden kann. Je mehr es dann den von __deets__ erwähnten impedance-mismatch gibt, um so schlechter ist das Ergebnis.

Grundsätzlich ist IMHO der rein automatisierte Ansatz, den JavaDoc populär gemacht hat und den Doxygen verfolgt, für Python und andere dynamische Programmiersprachen nicht so geeignet. Es wird schon einen Grund haben warum der alte Platzhirsch EpyDoc der für Python solche Dokumentation erstellt hat, seit 2008 nicht mehr weiterentwickelt wird und von Sphinx abgelöst wurde.

[noisefloor]

Hallo,

Gute Dokumentation zu schreiben ist deutlich schwieriger als den Code zu schreiben.

Absolut. Und ggf. zeitaufwendiger.

Ich hatte früher ja mal zwei kleine Python-Module "just for fun", ein Turm von Hanoi Solver und ein Morse En-/Decoder. Die Docstrings, welche die Nutzung / API dokumentiert haben, war am Ende länger als der Code selber. Aber man sollte halt alles so klar wie möglich machen. Python-Module, die dünn dokumentiert sind und wo man wohl möglich noch den Quelltext lesen muss, damit man es nutzen kann, sind einfach nur gruselig.

Gruß, noisefloor

[__blackjack__]

Wobei Python noch den Vorteil hat, dass man damit durchaus lesbaren Code schreiben kann, so dass es manchmal tatsächlich genau so leicht ist den Code zu lesen wie Text der erklären würde was der macht. Gruselig finde ich das lesen müssen des Codes eigentlich nur wenn der schlecht geschrieben wurde. Ich bin auch kein Fan davon alles wie bei JavaDoc-ähnlichen Dokumentationen zu dokumentieren, weil das zu trivialen, eigentlich nutzlosen Massen an Text führen kann.