mikrocontroller.net

Forum: PC-Programmierung Doxygen: Alle #if-Zweige des Präprozessors


Announcement: there is an English version of this forum on EmbDev.net. Posts you create there will be displayed on Mikrocontroller.net and EmbDev.net.
Autor: Walter T. (nicolas)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Guten Morgen,

gibt es in Doxygen die Möglichkeit, alle Zweige von Präprozessor-Makros 
in die Dokumentation aufzunehmen?

Oder andersherum: Gibt eine Möglichkeit, den Präprozessor komplett 
abzuschalten, ohne dass die Include-Graphen verloren gehen?

Autor: DPA (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Es gibt bei Stackoverflow ein zwei vorschläge dazu: 
https://stackoverflow.com/questions/26043007/make-doxygen-doxument-the-ifdef-parts-too

Ansonsten im Makefile halt was hinzufügen, das die Dateien kopiert und 
die ifdefs entfernt: (ungetestet)
SOURCES=$(wildcard src/*.c) $(wildcard src/**/*.c)
SOURCES=$(wildcard src/*.h) $(wildcard src/**/*.h)

docs: $(patsubst src/%,build/docsrc/%,$(SOURCES))
  doxygen Doxyfile

build/docsrc/%: src/%
  mkdir -p "$(dir "$@")"
  sed '/^#if/d;/#endif/d;/#else/d' <"$<" >"$@"

Aber wozu will man sowas überhaupt? Sollte man in der Doku nicht drin 
haben, was tatsächlich drin ist? Gibt es eventuell bessere alternativen 
zum Einsatz der ifdefs für das, wofür du diese momentan einsetzt?

Autor: Walter T. (nicolas)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
DPA schrieb:
> Es gibt bei Stackoverflow ein zwei vorschläge dazu

Der schlägt ja vor, Preprocessing zu deaktivieren, was mich die 
Baumdiagramme kostet. Letztere waren allerdings der Grund, überhaupt mit 
Doxygen zu arbeiten.

DPA schrieb:
> Sollte man in der Doku nicht drin
> haben, was tatsächlich drin ist

Naja, in der Doku des Quelltextes sollte drin sein, was implementiert 
wurde. Wenn es von einer Funktion zwei Varianten (z.B. für 
unterschiedliche Targets gibt), sollten natürlich beide dokumentiert 
sein.

Momentan behelfe ich mir damit, statt
#if TARGET == TARGET1
  ...
#elif TARGET == TARGET2
  ...
#else
  error ...
#endif
im Quelltext
#ifdef( TARGET1 )
  ...
#endif
#ifdef( TARGET2 )
  ...
#endif
und dann in Doxygen alle Targets zu definieren. Ist nur im Quelltext 
deutlich weniger geradlinig.

Autor: DPA (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ich mache in der regel ein Verzeichnis mit Unterverzeichnissen für jedes 
Target, und tue den Platformabhängigen Code dann in Dateien dort drin 
rein. Ich versuche dann immer, so wenig Platformabhängigen Code wie 
möglich zu haben, und schaue, dass der generische Code nicht von einer 
bestimmten Platform abhängig wird. In der regel mach ich das so, dass 
ich in Headern Interfaces definiere, und jede Platform diese dann 
implementiert. Beim compilieren lass ich dann die Dateien für andere 
Plattformen, als ich grad baue, einfach weg. Doxygen kann man die dann 
trotzdem alle vorwerfen, aber dort muss ich in der regel nicht viel 
Dokumentieren, weil das Interface schon zentral einmal dokumentiert ist 
und Programmunabhängig ist.

Autor: Walter T. (nicolas)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Ich bin mir nicht sicher, ob ich die Kernaussage richtig verstehe. 
Lautet sie "der Plattformabhängige Code ist so kurz, daß er nicht in die 
Doku braucht" ?

Autor: Dr. Sommer (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Walter T. schrieb:
> #ifdef( TARGET1 )
>   ...
> #endif
> #ifdef( TARGET2 )
>   ...
> #endif

oder
#if defined(TARGET1) || defined(DOXYGEN)
...
#endif
#if defined(TARGET2) || defined(DOXYGEN)
...
#endif

Alternativ einfach nur die Definitionen der Funktionen in #ifdef packen 
- dann sind die Deklarationen immer da, und wenn man eine unpassende 
Funktion benutzt gibt's einen "undefined reference" Linker Fehler.

Oder die Dinge für Target 1 in eine Datei, die für Target 2 in eine 
andere usw. Man muss dann die jeweils richtige Datei inkludieren, aber 
Doxygen sieht sie alle.

Oder die unpassenden Funktionen per SFINAE statt per Makros ausblenden, 
dann sieht Doxygen sie auch.

Oder verschiedene Klassen für die verschiedenen Targets definieren, und 
man muss dann je nach Target die richtige Klasse instanziieren. Doxygen 
sieht dann auch alles.

Autor: DPA (Gast)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Nunja, die Funktionalität meiner Programme ist in der regel bei den 
meisten Targets grösstenteils gleich oder ähnlich. Sagen wir, ich 
deklariere in einem Header die Platformabhängige Funktion "void 
setBlaMotorSpeed(int speed);", dann Dokumentiere ich dort z.B. "Setzt 
die Drehgeschwindigkeit von Motor bla. \param speed Geschwindigkeit in 
RPM im Uhrzeigersinn, negative Werte gegen den Urzeigersinn.". Wenn ich 
dann für verschiedene Plattformen andere Implementationen davon habe, 
dann schreib ich das dort in der Regel nicht nochmal hin. Wo der Motor 
angeschlossen ist steht wo anders, und interessiert nicht, wenn man nur 
wissen will, was die Funktion tut. Höchstens Wenn es noch was spezielles 
zu beachten gibt, schreib ich das hin.

Autor: Vincent H. (vinci)
Datum:

Bewertung
0 lesenswert
nicht lesenswert
Exakt jene Frage hab ich vor 5 Monaten ebenfalls auf stackoverflow 
gestellt:
https://stackoverflow.com/questions/55242882/doxygen-parse-everything-regardless-of-preprocessor-directive#

Fazit: Ich entferne die Direktiven via Python-Script und parse die 
temporäre Datei...

Antwort schreiben

Die Angabe einer E-Mail-Adresse ist freiwillig. Wenn Sie automatisch per E-Mail über Antworten auf Ihren Beitrag informiert werden möchten, melden Sie sich bitte an.

Wichtige Regeln - erst lesen, dann posten!

  • Groß- und Kleinschreibung verwenden
  • Längeren Sourcecode nicht im Text einfügen, sondern als Dateianhang

Formatierung (mehr Informationen...)

  • [c]C-Code[/c]
  • [avrasm]AVR-Assembler-Code[/avrasm]
  • [code]Code in anderen Sprachen, ASCII-Zeichnungen[/code]
  • [math]Formel in LaTeX-Syntax[/math]
  • [[Titel]] - Link zu Artikel
  • Verweis auf anderen Beitrag einfügen: Rechtsklick auf Beitragstitel,
    "Adresse kopieren", und in den Text einfügen




Bild automatisch verkleinern, falls nötig
Bitte das JPG-Format nur für Fotos und Scans verwenden!
Zeichnungen und Screenshots im PNG- oder
GIF-Format hochladen. Siehe Bildformate.

Mit dem Abschicken bestätigst du, die Nutzungsbedingungen anzuerkennen.