Alphatester für Dokumentationssystem

[igel457]

Hallo,

nachdem ich mit meiner mit Pasdoc generierten HTML-Sourcecode-Dokumentation für Andorra 2D (http://andorra.sf.net/docs/) nicht sonderlich zufrieden war, habe ich mich die letzten beiden Wochen drangesetzt und einen XML, SQL und GraphViz-Exporter für PasDoc nebst zugehörigem PHP-Script zusammengeschustert.

Dieses PHP Script formatiert die XML Dateien entsprechend, verlinkt alles untereinander und stellt eine mit SQL realisierte Volltextsuche in der Dokumentation zur Verfügung.

Da ich die Dokumentation jedoch nicht für mich, sondern vor allem für die Benutzer gebaut habe, würde ich mich freuen, wenn ihr euch das System mal anschauen könntet und konstruktive Kritik oder Feedback (gerne auch positives ) dazu äußert.

Über jeden gefundenen Bug würde ich mich freuen aber auch vor allem Meinungen zu Usability und Layout würden mich interessieren.

Haupt-URL:
http://andorracommons.sf.net/docs/

Suche:
http://andorracommons.sf.net/docs/index.php?q=

Das Ganze ist noch nicht für den produktiven Einsatz gedacht, unter anderem die URLs können sich noch ändern. Importiert sind momentan die komplette Source-Code-Doku für Andorra 2D (4.5.1), Audorra (SVN) und Andorra Commons (SVN).

Getestet wurde die Seite bisher ausschließlich mit Chrome und Firefox 3.6, Internet Explorer teste ich, sobald ich mein Windows mal wieder gestartet habe.

Bekannte Probleme/Fehler:
Das Ganze ist bis jetzt noch nicht ganz fertig, folgende Bugs sind mir (unter anderem bekannt)

• Enumerationen werden noch nicht angezeigt
• Überladene Funktionen werden noch nicht angezeigt
• BB-Code Tags werden in der Volltextsuche ungehighlighted angezeigt
• Die Unit-Übersichtsseite existiert noch nicht.
• Besonders im Audorra-Part sind einge Teile sehr gut Dokumentiert (TAu3DAudio), andere jedoch nicht

Getestet mit:

• Firefox 3.6
• Chrome
• Opera

Suchbegriffe/Themen zum Testen:
Da nicht jeder schnell mal ein paar Begriffe und Themen hat, hier ein paar Sachen um die Suche zu testen:

• TAu3DAudio
• audio play
• wasapi
• todo heck
• AuAudio
• openal

Crosspost zu DelphiGL: http://www.delphigl.com/forum/viewtopic.php?f=4&t=9328

Schonmal Danke,
Andreas

[Prototypjack]

Moin,

Ich habe mir das jetzt mal kurz angesehen und muss sagen: Sieht wirklich super aus!
Alles in allem wirkt das bis jetzt (obwohl es ja noch alpha / beta zu sein scheint) sehr stimmig und übersichtlich (imho). Die Suche funktioniert auch sehr gut, das einzige was ich dort ändern würde, wäre die Breite der Ergebnisliste, denn diese ist relativ schmal gehalten (und sieht hier sogar auf meinem Laptop mit kleiner Monitorgröße schon schmal aus).

Abschließend interessiert mich noch eins: Hast du vor die Modifikation von PasDoc, die hinter dieser Doku steht zu veröffentlichen? Ich finde dein System ist optisch das ansprechendste was ich bis jetzt gesehen habe und es fehlt der Delphi Community bis heute ein anständig aussehendes und funktionierendes opensource / freeware Code-Dokumentationssystem.

Grüße,
Max

[igel457]

Hallo,

erstmal Danke für das Lob.

Zitat von Prototypjack:

Hast du vor die Modifikation von PasDoc, die hinter dieser Doku steht zu veröffentlichen?

Ja, wenn es fertig ist. Nach der PasDoc Lizenz komme ich gar nicht drum herum

[mirage228]

Moin,

Unter Opera wird mir leider der eigentliche Seiteninhalt nicht korrekt angezeigt (vgl. Anhang)

Viele Grüße

[mkinzler]

Links wird bei mir auch nichts angezeigt ( FF4b1)

[BUG]

Wenn man sich die Abhängigkeiten einer Unit "fullscreen" anschauen möchte, passen die Beschriftungen nicht in die Boxen.

Beispiel:
depend.png

EDIT:
Browser: Firefox 3.6.6

[xZise]

Moin,
dieses grüne Rechteck, könnte man da nicht so Infos unterbringen. Also bei Properties zum Beispiel ob sie beschreibbar sind oder nicht? Außerdem sieht das ein bisschen komisch aus. Einmal steht bei den Properties die ganze Zeile drin und dann schön formatiert, aber dann steht bei den Functions der Code nicht formatiert drin.

Und irgendwie sieht das mit den doppelten Namen bei den Eigenschaften komisch aus.

MfG
Fabian

[xZise]

Moin,
ich weiß nicht ob es im Bereich des möglichen ist, aber ich würde bei dieser Grafik vielleicht das nicht so Spaghettisalat mäßig machen.

Außerdem wäre das praktisch, wenn man die Properties auch dokumentieren könnte (also was macht die property nicht ob sie existiert).

MfG
Fabian

[igel457]

Hi,

Zitat von xZise:

ich weiß nicht ob es im Bereich des möglichen ist, aber ich würde bei dieser Grafik vielleicht das nicht so Spaghettisalat mäßig machen.

Die Grafik wurde von Graphiviz eigentlich schon hochoptimiert, wenn das so kreuz- und quer aussieht ist das eher ein Hinweis auf schlechte Strukturierung des Sourcecodes. Eine bessere Idee habe ich hier nicht.
Da Au3DAudio aber die Top-Level-Unit schlechthin ist, ist das vielleicht nicht weiter verwunderlich...

Zitat von xZise:

Außerdem wäre das praktisch, wenn man die Properties auch dokumentieren könnte (also was macht die property nicht ob sie existiert).

Kann man - ich habe nur noch nicht überall alles dokumentiert:
http://andorracommons.sourceforge.ne...AdDraw#DllName

Trotzdem Danke für die Hinweise!
Andreas

[xZise]

Moin,
achso okay, hatte mich gewundert, weil ich keine Property anklicken konnte, aber die Methodennamen.

MfG
Fabian