Gibt es bessere Dokumentations-Generatoren als Doxygen oder solche die man als Ergänzung zu Doxygen nehmen sollte? Aktuell suche ich sowas für C/Keil.
:
Verschoben durch Admin
Doyxgan hab ich auch mal ausprobiert - und schnell im Müll versenkt weil der Autor offenbar überhaupt nicht verstanden hat worum es geht. Nämlich das: http://de.wikipedia.org/wiki/Literate_programming Es ist der falösche Ansaz, aus ein paar Programmtextzeilen eine Dokumentation automatisiert erzeugen zu wollen. Da steht nämlich nur Unissin drin. Hingegen ist es sehr schlau, aus einem eher langen Dokument den Quelltext zu extrahieren, um das Programm zu bekommen. Ich schreibe es in Word. Allerdings nur kleine Programme deren Doku quasi als Lehrmaterial dienen soll.
MaWin schrieb: > Es ist der falösche Ansaz, aus ein paar Programmtextzeilen > eine Dokumentation automatisiert erzeugen zu wollen. Da > steht nämlich nur Unissin drin. Das entspricht allerding sehr der Grundtendenz von C. Der Programmierer kann (fast) jeden Mist schreiben, ohne dass ihm der Compiler auf die Finger klopft. Genauso ist die Dokumentation die mit Doxygen extrahiert wird, nur so gut, wie die vom Programmierer eingearbeiteten Steuer-Kommentare...
@MaWin Ich habe noch nie Buchstaben lallen gesehen. Danke für den Spass und gute Nacht...
> Genauso ist die Dokumentation die mit Doxygen extrahiert wird, nur so > gut, wie die vom Programmierer eingearbeiteten Steuer-Kommentare... Nein, sie kann prinzipbedingt nicht gut werden. Ich hatte doch absichtlich den Wikipedia-Artikel wegen Doxygens Defiziten verlinkt.
Doxygen kann man nicht mal eben schnell ausprobieren und erwarten, dass man damit eine Dokumentation bekommt, welche man seiner Mutter als Lektüre empfehlen kann. Literarisches Programmieren ist ein interessanter Ansatz, den ich noch nicht kannte. Ist allerdings auch nicht so verwunderlich, dünkt es mich nicht so praxistauglich. Für ein mehrere KB grosse Projekt müsste ja ein ganzes Bücherregal voller Dokumentation geschrieben werden. Da der SW-Entwickler prinzipiell minimalistisch veranlagt ist, finde ich es wichtig, wenigstens das vorhandene Material zu einer Dokumentation verarbeiten zu können. Natürlich muss man dabei immer das Zielpublikum im Hinterkopf behalten: Doxygen dokumentiert vor allem die Schnittstellen.
Hallo zusammen, also ich arbeite seit Jahren mit Doxygen und den graphischen Erweiterungen. Es funktioniert gut. Allerdings ist es aus meiner Sicht wie so oft bei SW-Entwicklung. -Aufgabenstellung/Beschreibung des AG unklar nicht eindeutig -Die Software wächst und mutiert wie Krebs -Schnell mal was probieren -Verschiedene Programmierstile -Kommentare werden später gemacht -... Da kann das beste Tool nicht helfen. Wenn Software von Begin an richtig design wird und mit den richtigen Werkzeugen und Vorgaben gearbeitet wird funktioniert das auch. Selbst wenn mehrere Leute an einem Projekt arbeiten. Literate_programming ist ein Ansatz, aber wohl eher für Leute die sich nur theoretisch mit SW-Entwicklung befassen. Und 'programmieren' in Word lasse ich einfach mal so im Raum stehen. Ich werde wohl weiter mit Doxygen arbeiten. Übrigens Doxygen ist ein OpenSource Projekt. Es steht jedem frei sich an der Verbesserung des Programms zu beteiligen. Viele Grüße aus Berlin
Hi, falls du für Cortex-M entwickelst: Hast du mal in die CMSIS Files geschaut? Das ist alles Doxygen :-) Auch die Headerfiles für die Mikrocontroller, die ich aus der Spec. der Hersteller (s. CMSIS-SVD) generiere, enthalten ebenfalls Doxygen Kommentare... VG, /th.
StinkyWinky schrieb: > Literarisches Programmieren ist ein interessanter Ansatz, den ich noch > nicht kannte. Ist allerdings auch nicht so verwunderlich, dünkt es mich > nicht so praxistauglich. Für ein mehrere KB grosse Projekt müsste ja ein > ganzes Bücherregal voller Dokumentation geschrieben werden. Stammt ja auch von Donald E. Knuth, und der hat sich schließlich auch erstmal ein Textsatzsystem geschrieben, nur weil ihm das, was andere bis dahin zustande gebracht haben, nicht schön genug aussah. ;-) Doxygen leidet an vielen Stellen unter "Voreingenommenheit", wobei das im Laufe der Jahre ein wenig besser geworden ist. Vor 10 Jahren konnte man es praktisch nur für C++-Programmierung benutzen, jede popelige struct, die man definiert hat, wurde sofort wie eine Klasse behandelt. Mittlerweile kann man mehr finetuning betreiben, aber der Ursprung aus der Welt der OO-Programmierung (vorrangig C++ oder Java) ist ihm immer noch deutlich anzumerken. Was Besseres habe ich allerdings auch noch nicht gefunden, sieht man mal davon ab, dass man die Doku halt wirklich komplett from scratch schreibt (oder es noch weiter treibt und bei literate programming rauskommt ;).
MaWin schrieb: > Doyxgan hab ich auch mal ausprobiert - und schnell > im Müll versenkt weil der Autor offenbar überhaupt > nicht verstanden hat worum es geht. Nämlich das: Du hast es nicht verstanden, MaWin. Doxygen ist hauptsächlich geeignet um aus bestehendem und sogar komplett undokumentiertem Quelltext eine Doku zu generieren. Gerade als Retter in der Not, der die Auswüchse mittlerweile geflohener Entwickler gradebiegen soll, kann man von Doxygen profitieren. Aber deine werte Meinung ist natürlich viel wahrer als meine, eh klar. MaWin schrieb: > Ich schreibe es in Word. Oh, das ist natürlich ein sehr geeignetes Tool zur Softwareentwicklung... MaWin schrieb: >> Genauso ist die Dokumentation die mit Doxygen extrahiert wird, nur so >> gut, wie die vom Programmierer eingearbeiteten Steuer-Kommentare... > > Nein, sie kann prinzipbedingt nicht gut werden. > Ich hatte doch absichtlich den Wikipedia-Artikel wegen Doxygens > Defiziten verlinkt. Deswegen hast du noch lange nicht recht mit deiner Schwarz/Weiß Denke. Wie kommst du eigentlich darauf dass jedes Tool zu deiner speziellen Auffassung von sowieso Allem passen muss?
Um aus diesem Thread noch ein wenig Sinnvolles herauszuholen, empfehle ich alle Vor- und Nachteile OBJEKTIV darzulegen. Sonst könnte man den Eindruck bekommen, man macht hier die schlechten Ergebnisse anderer Programmierer für das Scheitern eines Programms verantwortlich.
stiller Beobachter schrieb: > Um aus diesem Thread noch ein wenig Sinnvolles herauszuholen, > empfehle ich alle Vor- und Nachteile OBJEKTIV darzulegen. 100% ACK Doxygen-Vorteile: 1. freie Software 2. einfach zu bedienen mit Doxywizard Doxygen-Nachteile: 1. allgemeine Dokumentation funktioniert aus echten Quelltext-Kommentaren heraus (prinzipbedingt) nicht gut fallen mir jetzt auf Anhieb ein.
> Für ein mehrere KB grosse Projekt müsste ja ein > ganzes Bücherregal voller Dokumentation geschrieben werden Nicht unbedingt. Du musst exakt das dazuschreiben, was du unter Dokumentation verstehst. Wobei genau das, was als Programmcode drinsteht, NICHT dupliziert ist (und deswegen bei jeder Änderungen angeglichen werden müsste) und genau das, was du normalerweise als Kommentar am Programmtext hättest, automatisch bereits in der Dokumentation steht. Es ist eher im Gegenteil so, daß die 'Dokumentation' aus einem automatisierten Dokumentationssystem ("übernehmen wir jede Funktion mit ihrem Funktionskopf in die Doku") zu dermassen viel Papierverkhau führt, daß sowieso keiner sie mehr liest, schon alleine deswegen weil ihre Inhalte zu 99% bloss blödes Gelaber ohne sinnvollen Inhalt ist. Für mich beginnt die Doku etwas früher, nämlich mit der Überschrift "Dieses ist das BlaBlaBla Projekt" und "es dient folgendem Einsatzzweck unter folgendem Rahmen" und "besteht aus diesem Kram und ist so per Compiler etc. erstellbar" verwendet dieses "Dateiformat und von aussen relevanten Datenstrukturen" und bietet "als API jene aufrufbaren Methoden" und dann erst kommt der grosse Block "und ist so implementiert" wobei dort eher der grobe Überblick als die exakte Beschreibung aller einzelnen winzigen Hilfsfunktionen angemessen ist (und genau desegen sind Dokusystem die jede derartige Schnapsfunktion akribisch auflisten eher blöd), denn die überblickt eh keiner, zumindest bei realen Programmen statt Kinderspielzeug. Leider fehlt genau diese Anfangsdoku meist, oder ist in erbärmlichem Zusttnd "Compilieranweisung hab ich befolgt, geht nicht", eben weil sie NICHT tatsächliche Basis des aktuellen Herstellungsprozesses ist (es wird genau das MAKEFILE verwendet welches in der Doku steht) sondern 'dank' blöder Software (Microsoft schreibt halt gerne selbst seine makefiles raus, früher zumindest, heute nicht mla mehr das) immer nur eine Kopie irgendeinen veralteten Zustandes.
> Doxygen ist hauptsächlich geeignet um aus bestehendem und sogar > komplett undokumentiertem Quelltext eine Doku zu generieren. Mann, Mann, Loonix, du solltest keine Beiträge schrieben in denen so offensichtlich ist, daß du das Zeug von dem zu schreibst nie ausprobiert hast, denn GENAU diese Doku ist es, die man nur ins Bücherregal stellen kann, weil sie riesig aber absolut nicht erhellend ist. > allgemeine Dokumentation funktioniert aus echten > Quelltext-Kommentaren heraus (prinzipbedingt) nicht gut So ist es. > Aber deine werte Meinung ist natürlich viel wahrer als meine Und so natürlich auch. Ich mach mir das mit der Bewertung recht leicht: Ich guck mir an, was andere Leute zu meiner Doku sagen. Und die finden meine Doku erhellend, und concise, und die aus anderen Quellen unübersichtlich, bulky, unlesbar. Oder ich schau mir an, wie meine Doku entsteht, nebenbei, und verfolge Projekte anderer Leute die auf Doxygen aufsetzen, die selbst nach mehreren Jahren nichts verwertbares (das beurteile nicht ich sondern Kunden und Chefs) rausbekommen haben. Und das nicht im Einzelfall, sondern in 30 Jahren Praxis.
MaWin schrieb: >> Doxygen ist hauptsächlich geeignet um aus bestehendem und sogar >> komplett undokumentiertem Quelltext eine Doku zu generieren. > > Mann, Mann, Loonix, du solltest keine Beiträge schrieben in denen > so offensichtlich ist, daß du das Zeug von dem zu schreibst nie > ausprobiert hast, > denn GENAU diese Doku ist es, die man nur ins Bücherregal > stellen kann, weil sie riesig aber absolut nicht erhellend ist. Das ist - gelinde gesagt - totaler Unsinn. Man merkt hier viel mehr, daß du Doxygen nie überhaupt richtig ausprobiert hast. Ich habe Doxygen schon öfters genau dafür benutzt, und es gibt einen sehr guten Überblick über die Struktur eines Programms und erleichtert das Einarbeiten in unzureichend dokumentierten Code sehr. Das ist das erste, was ich bei fremdem Code mache - Doxygen drüberlaufen lassen. Dazu muß man aber auch vor der Generierung erstmal alle Doxygen-Features einschalten. Ins Bücherregal stelle ich das nicht, weil ich es nicht ausdrucke. Das wäre auch unsinnig, denn dann wären ja die ganzen Verlinkungen, die es erst richtig brauchbar machen, alle weg. > Ich mach mir das mit der Bewertung recht leicht: > Ich guck mir an, was andere Leute zu meiner Doku sagen. > Und die finden meine Doku erhellend, und concise, > und die aus anderen Quellen unübersichtlich, bulky, unlesbar. Das sagt aber erstmal nichts über den Nutzen der prinzipiellen Vorgehensweise, sondern nur über die Qualität der Umsetzung aus.
MaWin schrieb: > Für mich beginnt die Doku etwas früher, nämlich mit der Überschrift > "Dieses ist das BlaBlaBla Projekt" und "es dient folgendem Einsatzzweck > unter folgendem Rahmen" und "besteht aus diesem Kram und ist so per > Compiler etc. erstellbar" verwendet dieses "Dateiformat und von aussen > relevanten Datenstrukturen" und bietet "als API jene aufrufbaren > Methoden" und dann erst kommt der grosse Block "und ist so > implementiert" wobei dort eher der grobe Überblick als die exakte > Beschreibung aller einzelnen winzigen Hilfsfunktionen angemessen ist > (und genau desegen sind Dokusystem die jede derartige Schnapsfunktion > akribisch auflisten eher blöd), denn die überblickt eh keiner, zumindest > bei realen Programmen statt Kinderspielzeug. Auch das kann man mit Doxygen machen. Man muss ja nicht unbedingt C++ Quelltexte durch Doxygen jagen. Die Doku von Doxygen (das Handbuch) ist auch mit Doxygen erstellt.
MaWin schrieb: > Mann, Mann, Loonix, du solltest keine Beiträge schrieben in denen > so offensichtlich ist, daß du das Zeug von dem zu schreibst nie > ausprobiert hast, Da du eine der meinen vollkommen umgekehrte Wahrnehmung zu haben scheinst, nehme ich das mal als deine Anerkennung meiner Berufserfahrung. Danke dafür. MaWin schrieb: >> Aber deine werte Meinung ist natürlich viel wahrer als meine > > Und so natürlich auch. Auch das passt zu meiner Annahme ;) MaWin schrieb: > Ich mach mir das mit der Bewertung recht leicht: > Ich guck mir an, was andere Leute zu meiner Doku sagen. > Und die finden meine Doku erhellend, und concise, > und die aus anderen Quellen unübersichtlich, bulky, unlesbar. Das möchte ich nicht bestreiten. Es geht aber doch an der ursprünglichen Frage vorbei, es sei denn du wolltest dich als "der Bessere Dokumentations-Generator" in Person dem TE anbieten. Ergänze doch die Vorteil/Nachteil-Liste, wegen deiner > 30 Jahren Praxis. die ich dir durchaus abnehme, solltest du da mehr beitragen können als "ich programmiere literarisch in WORD".
Weitere Vorteile: 1. Da die Doku quasi im Code enthalten ist, hat man, Falls mal was abhanden kommt, bei Versionskontrollsystemen auch die älteren Versionen der Doku zur Verfügung. 2. Doku Backups werden mit dem Source durchgeführt. 3. Keine Umschaltung zwischen Programmen nötig. Wenn man in Doxy eingearbeitet ist, muss man gegen Feierabend nicht mehr noch die Doku aus den Fingern saugen, sondern kann das praktisch "on the fly" erledigen. Da der Sourcecode sowieso kommentiert wird, braucht es nur ein wenig guten Schreibstil um ohne viel Nacharbeit ein brauchbares Ergebnis zu erhalten. 4. Immenser Vorteil gegen Eindateidoku wie bei Word etc. ist die mögliche Übersichtlichkeit der Doxy Doku.
5. Doxygen erstellt in Verbindung mit dem Dot-Tool automatisch Bezugsdiagramme, die man als .PNG auch gerne in WORD reinholen kann...
Wer nicht dokumentieren will, kann das mit jedem Tool machen ;)
Naja, in dem betreffenden Code finde ich vieles was auf den Obfuscated C Code Contest gehört: Ein Dutzend Defines nicht in einem Header-File sondern als Projekt-Option, natürlich ohne Kommentar und Dokuentation, und Funktionen die über 1000 Zeilen lang sind! Naja, da muss man halt durch und komplett lesen.
Ich weiß gar nicht, wie man auf die Idee kommen könnte, Doxygen sei unbrauchbar. Natürlich kann man nicht erwarten, dass aus Spaghetticode, den kein Mensch versteht, mit Doxygen auf wundersame Weise eine erhellende Dokumentation entsteht. Der Vorteil bei Doxygen ist jedoch, dass man auf einfache Art (also eine leicht zu erlernende Methode, Kommentare zu setzen) eine sehr mächtige Dokumentation erstellen lassen kann. Eventuell ist es auch gar nicht das "speziell dokumentieren", sondern dass man überhaupt dokumentiert. Auch die Call- und Dependency-Graphen sind durchaus praktisch, selbst wenn keine Zeile Kommentar geschrieben wurde, da sie die Stuktur gut wiedergeben. Wie man nach langer Berufserfahrung auf komplette Unbrauchbarkeit schließen kann, ist mir jedoch nicht klar; außer - man hat sich in der Tat noch nicht ausgiebig mit Doxygen beschäftigt - man hat falsche Erwartungen von einem Computersystem. Ist eben kein Harry-Potter-Programm. Um ganz objektiv zu sein: Doxygen bietet eine komfortable Möglichkeit, eine Dokumentation zu verfassen. Das Problem bei separat geschriebenen Dokumentationen ist doch, dass Dokumentation und Implementierung zwangsläufig mit der Zeit divergieren; bei Kommentaren direkt über dem Code fällt es doch sofort auf, wenn etwas nicht passt. Eine Bitte an MaWin: An welcher Stelle hat Doxygen deine Erwartungen nicht erfüllt? Und bitte nicht "der hatte weniger Erfolg und die Doku gefällt keinem", sondern aus deiner Sicht.
Zuckerle schrieb: > Alles Unsinn, ein gutes Programm braucht nicht dokumentiert zu werden, > es dokumentiert sich von selbst. Genau, gib dem Zucker Affen.
Nico Sch. schrieb:
> Spaghetticode
Der beste Spaghetticode, welcher bisher nur mit umfassenden
Powerpointpresentationen dem Chef als innovativ untergeschoben werden
konnte, wird natürlich durch Doxygen als scharlatanistisches Obfuskat
entlarvt. Dagegen muss geklagt werden, Doxygen sollte verboten werden.
Also ich finde Doxygen nicht schlecht, es ist schon brauchbar. Aber vielleicht gibt's inzwischen bessere Alternativen. Wohl wegen Firmen-Scripten bekomme ich auf dem Firmen-Rechner vom Doxygen keine Grafiken. Da muss ich mal den Sourcecode auf einen anderen Rechner packen.
Erwin Meyer schrieb: > Also ich finde Doxygen nicht schlecht, es ist schon brauchbar. > Aber vielleicht gibt's inzwischen bessere Alternativen. > > Wohl wegen Firmen-Scripten bekomme ich auf dem Firmen-Rechner vom > Doxygen keine Grafiken. Firmen-Skripte? Hast du die Graphen auch eingeschaltet (sind per Default aus) und dot installiert?
Erwin Meyer schrieb: > Wohl wegen Firmen-Scripten bekomme ich auf dem Firmen-Rechner vom > Doxygen keine Grafiken. Da muss ich mal den Sourcecode auf einen anderen > Rechner packen. Damit gehen wir zwar komplett vom ursprünglichen Thema weg, aber hast du denn überhaupt ein Dot-Tool installiert und den Pfad im Doxyfile angegeben? (Sonst gibts auch keine Grafiken)
Jetzt wird es interessant, und nicht mal am Thema vorbei, wenn ich das so sagen darf. Doxygen als Alternative zu Doxygen, mit dem Unterschied das man es konfiguriert statt zu verdammen. Um eine Alternative vergleichen zu können, muss einem natürlich bewusst sein was man da ersetzen möchte. Welche von erfahrenen Benutzern empfohlenen Einstellungen sinnvoll sind für die eine oder andere Sache spart einem Zeit bei der Einarbeitung und sollte hier nicht fehlen. Danke, vielleicht gibt es ja eine Zusammenfassung zur Doxy-Doku für die Lesefaulen, oder was in deutscher Sprache.
Loonix schrieb: > 1. allgemeine Dokumentation funktioniert aus echten > Quelltext-Kommentaren heraus (prinzipbedingt) nicht gut Kann man so nicht sagen. Niemand zwingt einen ja, über jede Funktion den Doxygen-Block drüber zu setzen. Interne Funktionen, die nur ein paar Zeilen später benutzt werden und sonst für niemanden von Interesse sind, kann man ganz einfach mit einem Stino-Kommentar versehen statt eines solchen, den Doxygen dann reinzieht. Damit vermeidet man das von Manfred beschworene "30 Meter Doku ohne Wert"-Problem. Außerdem kann man einfach mal separate Dateien (unabhängig vom Quelltext) mit beilegen, die man dem Doxygen mit in die Hand drückt. Über die Gruppenbezüge lassen sich diese dann über die aus den Quelldateien automatisch generierten Teile einfügen, sodass man für bestimmte Dinge einfach zusätzliche "Prosa" hinterlegen kann. Das geht brauchbar, hat nur zwei Nachteile: Eine solche Datei muss syntaktisch trotzdem noch die Doku in einem Kommentar gemäß der Kommentarkonventionen der gewählten Programmiersprache haben. Damit hat man, wenn man sich nicht gerade noch einen eigenen Highlight-Modus für den Editor dafür baut, kein visuelles Markup beim Schreiben dieser Dokumentation. (Könnte man, wenn man nicht MaWin heißt und aus religiösen Gründen sowieso nur .bat-Dateien benutzt, mit ein wenig make-Mimik lösen, indem man die eigentlichen Doku-Files vor dem Doxygen-Lauf extern um die Doxygen-Kommentare erweitert, ohne dabei den "Master" selbst zu ändern.) Der zweite Nachteil ist, dass Doxygen in Verbindung mit diesen Gruppierungen immer mal wieder ein "interessantes Eigenleben" zu entwickeln scheint, bei dem bestimmte Dinge am Ende nicht so zusammen passen, wie es eigentlich sein sollte, ohne dass man in der umfänglichen Statusausgabe wirklich einen Hinweis findet, was ihm jetzt eigentlich nicht geschmeckt hat. Man muss die generierte Doku also vor einem Software-Release nochmal ordentlich ansehen, dass auch wirklich alles gewünschte dabei ist und alles so gruppiert ist, wie man sich das vorgestellt hatte.
Habe mit Zwiespalt die Diskussion bis hierher verfolgt und stelle mir folgende prinzipielle Frage: Welche Dokumentation ist gemeint? -> Schnittstellenbeschreibung? -> Funktionsbeschreibung? -> Programmierhandbuch? -> Anwendungsbeschreibung? -> ... Je nach Typ wird man unterschiedliche Verfahren (Tools) anwenden müssen und, meine eigene (jahrelange) Erfahrung, man wird ab einem gewissen Grad nicht drumherum kommen, auch mal einen Text "freihändig" in einem entsprechenden Dokument zu formulieren. Gerade z.B. eine Beschreibung an Hand von spezifischen Beispielen ist aussagekräftiger, als eine formale Beschreibung der Funktion mit ihren Parametern. Doxygen ist ja nicht schlecht und man kann bestimmt ganz viel damit machen, wenn man es richtig anwendet. Aber nach meiner Meinung kann es auch einen Quelltext schwer lesbar machen, wenn 20 Zeilen Kommentare/Steuerkommandos für 2-3 Zeilen tatsächlichen Code den Lesefluss beeinträchtigen... Doxygen hat zweifellos seine Berechtigung, reicht aber für eine vernünftige Dokumentation nicht aus! Mahlzeit
> An welcher Stelle hat Doxygen deine Erwartungen nicht erfüllt?
Die behauptete Leistungsfähigkeit, bei bestehendem "fremdem"
Programmtext einem eine Übersicht über die Programmstruktur
liefern zu können, ist ein totaler Flop. Da ist der Quelltext
lesbarer als das was Doxygen daraus macht, der bläht nur den
Seitenumfang auf.
Wenn man den Programmtext mit allen Kommentaren versieht, damit
Doxygen glücklich ist, Funktionheader etc., bläht man den
Programmtext auf ein vielfaches auf, senkt also dessen
Übersicht erheblich. Zudem ist das, was Doxygen dann daraus
extrahiert, auch nicht sinnvoll.
Beides ist aber gar nichts, was ich verlange, sondern nur das
mit dem hier manche Doxygen bewerben.
Bei uns war der grösste Nerv, daß es beim Import bestehender
Doku (es gab halt zu den als API wichtigen implementierten
Funktionen komplette Benutzerbeschreibungen in Word DOC im
WinHelp Format, die versuchshalber auch in XML konvertiert
wurden, in denen alles, vom Namen über Parameter zur
Funktionsbeschreibung mit Beispielen als Testfälle und
Verweisen auf Geschwister (Bilder und Formeln haben wir
gar nicht erwartet daß die rüberkommen)) die Farbe der
Buchstaben vergessen hat (quasi das Syntax-Highlight der
bestehenden Doku), und daß es bei einigen hundert Seiten
sich dermassen verhaspelt hat, daß eine Endlosschleife lief,
den hunderten von Seiten die mit anderen Dokutools in wenigen
Sekunden prozessiert wurden.
Das war aber nur ein Fall von dem ich weiß (weil ich ihn selber
kontrolliert habe), ähnliche Erfahrungen haben andere Gruppen
gemacht, wie gesagt, man sitzt in einem Projekt seit 2 Jahren
daran eine kundenakzeptable Doku mit Doxygen zu erstellen, die
man mit anderen Tools in wenigen Monaten fertig gehabt hätte.
Jörg Wunsch schrieb: > Loonix schrieb: >> 1. allgemeine Dokumentation funktioniert aus echten >> Quelltext-Kommentaren heraus (prinzipbedingt) nicht gut > > Kann man so nicht sagen. > >... Ja, die Aussage wird den Möglichkeiten von Doxygen wirklich nicht gerecht. Für die Pro/Kontra-Liste brauchte ich aber wenigstens einen Kontra-Punkt. Danke dass du dir die Mühe gemacht hast, dies weiter auszuführen.
Entwicker schrieb: > Aber nach meiner Meinung kann es > auch einen Quelltext schwer lesbar machen, wenn 20 Zeilen > Kommentare/Steuerkommandos für 2-3 Zeilen tatsächlichen Code den > Lesefluss beeinträchtigen... Die Doxygen-Kommentare müssen nicht im selben File stehen.
MaWin schrieb: > man sitzt in einem Projekt seit 2 Jahren > daran eine kundenakzeptable Doku mit Doxygen zu erstellen, die > man mit anderen Tools in wenigen Monaten fertig gehabt hätte. Na dann sag uns doch jetzt mal konkret, welches von den folgenden Tools besser ist als Doxygen, denn wir lernen doch alle gern dazu: http://en.wikipedia.org/wiki/Comparison_of_documentation_generators
> welches von den folgenden Tools besser ist
Da du weisst, daß ich Word verwende (welches dann nach Macrolauf
gedruckte Handbücher, WinHelp und HTML als Output aus derselben Quelle
erzeugt) daher trifft von der Liste nichts auf mich zu.
Obwohl eine Gruppe mit Document X! dem Hören nach ganz glücklich ist,
aber ich habe keine eigene Erfahrung damit.
Verwendet habe ich mal RoboHelp, aber dessen Zeit ist vorbei seit dem
BlueSky das an Adobe verkauft hat. Auch die d.s.e FAQ führe ich per
Editor, weil es einfach sehr praktikabel ist sich nur um Inhalte kümmern
zu müssen, obwohl ich mir einen fehlerfreieren TXT->HTML Formatter
vorstellen könnte und einige Tools (Link Validator) in akzeptabler Form
vermisse.
Am microcontroller.net-Wiki sieht man, daß es an Inhalten mangelt, wenn
das Werkzeug zu viel Mühe macht. Es hat schon mahr als ein mal jemand
angefragt ob er die Inhalte der d.s.e FAQ da reinschreiben dürfte und
von mir das OK bekommen, aber nie wurde es gemacht: Die Leute haben
entdeckt, daß es zu viel Arbeit macht. Kann ich verstehen, ich hab dazu
auch keine Lust, die FAQ selbst zu pflegen machte nur einen Bruchteil
der Arbeit.
Rolf Magnus schrieb: >> Wohl wegen Firmen-Scripten bekomme ich auf dem Firmen-Rechner vom >> Doxygen keine Grafiken. > > Firmen-Skripte? Hast du die Graphen auch eingeschaltet (sind per Default > aus) und dot installiert? Also inzwischen ist auch dot installiert und damit gibt es schöne Graphen. Allerdings sieht man da das einige Funktionen über 30 andere aufrufen und sogar sich selbst.
Thread beobachten
Seitenaufteilung abschaltenBitte melde dich an um einen Beitrag zu schreiben. Anmeldung ist kostenlos und dauert nur eine Minute.
Bestehender Account
Schon ein Account bei Google/GoogleMail? Keine Anmeldung erforderlich!
Mit Google-Account einloggen
Mit Google-Account einloggen
Noch kein Account? Hier anmelden.