Ich versuche, eine Python-Klasse mit Doxygen zu dokumentieren. Die Klasse stellt eine Reihe von Eigenschaften über d-bus zur Verfügung, aber diese haben keine entsprechenden öffentlichen Getter / Setter in der Python-Klasse. Stattdessen werden sie über eine Schnittstelle für d-Bus-Eigenschaften implementiert (Set / Get / GetAll / Introspect).
Was ich tun möchte, ist, diese Eigenschaften mit etwas wie diesem zu dokumentieren:
## @property package::Class::Name description
Das ganze Paket :: Klasse funktioniert (die gleiche Methode findet Funktionen, also findet sie die richtige Klasse).
Beim Ausführen von doxygen erhalte ich den folgenden Fehler:
warning: documented function ''package::Class::Name' was not declared or defined.
Ich kann mit einer Warnung leben, aber leider erscheint die Eigenschaft nicht in der Dokumentation, die für die Klasse generiert wurde, daher ist es nicht nur eine Warnung, sondern es wird auch zum Schweigen gebracht.
Meine Frage ist also, wie kann ich, wenn möglich, das nicht existierende Property-Member in den generierten Dokumenten erscheinen lassen?
Definieren Sie das Attribut in einem if 0: -Block:
Dies wird dazu führen, dass es in der Dokumentation vorhanden ist (getestet mit doxygen 1.8.1.2-1 auf debian-squeeze ). Das Attribut wird niemals zur Laufzeit zur Existenz kommen, und tatsächlich sieht es so aus, als ob der Python-Bytecode-Optimierer if-Anweisung und ihren Körper vollständig eliminiert.
Ich habe mir vorher etwas Ähnliches angeschaut und konnte keinen direkten Weg finden, Doxygen dazu zu bringen, ein undefiniertes Mitglied zu dokumentieren. Es gibt zwei grundlegende Kludges, die Sie hier verwenden können:
1.) Erzeugen eines Dummy-Objekts (oder Dummy-Elemente) für Doxygen zur Inventarisierung, die im Live-Code nicht existieren.
2.) Wenn die Anpassungen, die Sie benötigen, ziemlich vorhersehbar und regelmäßig sind, können Sie eine INPUT_FILTER schreiben. für doxygen, die Ihre Dateien übernimmt und vor dem Parsing konvertiert. Es gibt einige Probleme mit dieser Methode - meistens, wenn Sie planen, den Code in die Dokumentation aufzunehmen und der Filter Zeilen aus der Datei hinzufügen / entfernen muss, sind die Zeilennummern, die er anzeigt, aus und alle Codefenster, die mit angezeigt werden Die Dokumentation wird um diese Zeilenanzahl deaktiviert. Sie können auch die Option zum Filtern der angezeigten Quellen aktivieren, um diese anzupassen. Je nachdem, wer der Benutzer Ihrer Dokumentation ist, kann es jedoch verwirrend sein, dass die Kopie in Doxygen nicht genau mit der tatsächlichen Quelle übereinstimmt.
In unserem Fall verwenden wir ein Python-Skript, das Doxygen von der Kommandozeile mit dem Dateipfad als arg ausführt. Wir lesen die angegebene Datei und schreiben, was wir Doxygen stattdessen interpretieren wollen. Wenn Sie die in doxygen angezeigten Quellkopien auch zum Filtern benötigen, können Sie FILTER_SOURCE_FILES zu YES .
Tags und Links python doxygen properties