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! :thumb:
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:

Zitat von Prototypjack (Beitrag 1034835)

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:
Anhang 31640

EDIT:
Browser: Firefox 3.6.6

[igel457]

Probleme analysiert und nach langen rumbasteln mit Shellscripts und Imagemagick wirkungsvoll umschifft ;-)

PS: Der Seitencache ist aktiviert, um die Änderungen zu sehen die Seite komplett neu laden.

[BUG]

Zitat:

Zitat von igel457 (Beitrag 1034867)

und nach langen rumbasteln mit Shellscripts und Imagemagick wirkungsvoll umschifft ;-)

:thumb:

[xZise]

Wow sieht schonmal cool aus!

MfG
Fabian

[mirage228]

Also da es nun auch im Opera funktioniert, auch ein Lob meinerseits: Sieht sehr gut aus.

Was ich mir noch wünschen würde:
- Schneller zwischen Funktionen navigieren können. Was mir spontan einfiel, wäre in der Breadcrumb-Bar oben beim Klick auf den Pfeil eine Liste aller Unterelemente anzuzeigen (wie bei Windows 7) - oder eine Liste der weiteren Funktionen rechts (evtl. sogar in Kombination mit dem Class tree).
- Die einzelnen Bereiche in den Übersichtsseiten (Structures, Properties, z.B.) sollten ein- und ausklappbar sein.
- Die Methoden sollten evtl. auch vollständig alphabetisch sortierbar sein

Aber insgesamt schon mal ein :thumb: - weiter so.

[igel457]

Danke für das Lob und die guten Vorschläge, ich schaue mal wie ich das umsetzten kann.

Momentan versuche ich den nun doch ca. 1200 Zeilen langen PHP-Code von einer auf mehrere Include-Dateien aufzuspalten und meine Klassen ein wenig mehr auf das MVC-Schema umzubauen um den Code so flexibel wie möglich zu haben, damit ich Teile später wieder verwerten kann (die erstaunlich gut und flott funktionierende Suche z.B.) und der Sourcecode für andere nützlich ist.

Für weitere Vorschläge/Probleme bin ich natürlich weiterhin offen,
Andreas

[s.h.a.r.k]

Guten Abend,

alles in allem finde ich es sehr gut :) wo kann man das runterladen? :mrgreen: ja, ich weiß, es gibts noch nicht...

ABER
- die 2-3px Farbleisten links sind eher suboptimal für das Verständnis. Du könntest hier die Description in einen Kasten einbauen (sehr dezentes grau mit 1px Rahmen). Die Überschriften stehen ja schon für sich selbst und benötigen an sich keinerlei Farbe. Sollte der Text aber mal so lang sein, dass keine Überschrift zu sehen ist, so benötigt der User aber immerhin eine Legende, welche Farbe der Leiste nun was bedeutet. Daher sind diese eigentlich überflüssig.
- Zum Theme Legende noch was: welche Farbe bei den Methoden steht für welche Eigenschaft?! -> Legende hinzufügen ;) ganz unten oder rechts von der Überschrift (Functions) wäre diese ganz passend.
- Functions (und Proceduren) heißen in Klassen eigentlich Methoden, oder? :gruebel:
- Verlinkung unter Class Tree Visualisation.

[idefix2]

Hallo,

finde ich wirklich sehr gelungen. Optisch 1a.

Das einzige, was mir auf Anhieb aufgefallen ist, was ich ändern würde: in der Class tree visualization sollten die Pfeile doch eher in die andere Richtung zeigen, vom Vorfahr zur abgeleiteten Klasse?

[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

[Valle]

Hallo,

Zitat:

Zitat von idefix2 (Beitrag 1035057)

Das einzige, was mir auf Anhieb aufgefallen ist, was ich ändern würde: in der Class tree visualization sollten die Pfeile doch eher in die andere Richtung zeigen, vom Vorfahr zur abgeleiteten Klasse?

In UML ist es üblich, die Pfeile für eine Vererbung in Richtung des Parents zeigen zu lassen.

Liebe Grüße,
Valle

[igel457]

Danke für die Beiträge, das ist ganau das Feedback, das ich mir gewünscht habe. Ich schaue was sich machen lässt.

[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:

Zitat von xZise (Beitrag 1035271)

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. :wink: Eine bessere Idee habe ich hier nicht.
Da Au3DAudio aber die Top-Level-Unit schlechthin ist, ist das vielleicht nicht weiter verwunderlich...

Zitat:

Zitat von xZise (Beitrag 1035271)

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

[igel457]

So, ich bin mit meinem "Refactoring" auf der PHP Seite jetzt fertig, wenn alles glatt gelaufen ist, hat sich nach außen hin nichts geändert.

Ich habe den PHP-Quelltext mal angehängt, vielleicht kann irgendein PHP-Profi hier mal drüber schauen und seinen Senf dazu abgeben.

[himitsu]

Zitat:

Zitat von igel457 (Beitrag 1035320)

Ich habe den PHP-Quelltext mal angehängt, vielleicht kann irgendein PHP-Profi hier mal drüber schauen und seinen Senf dazu abgeben.

Hast du denn nichts gelernt?
Am Ende schreibst du alles nochmal Neu, weil man Vieles hätte besser machen sollen/müssen. :lol:

(z.B. statt require und include das coole AutoLoad)

[igel457]

Autoload ist meiner Meinung nach sehr pöse, da man so wenigstens noch in Teilen kontrolle darüber hat, welcher Teil
welche Abhängigkeiten zu anderen Dateien hat... Aber ich schätze das ist wohl nur eine Einzelmeinung.

Zitat:

Am Ende schreibst du alles nochmal Neu, weil man Vieles hätte besser machen sollen/müssen

Ich habe mir gedacht, ich verwende wenigstens eigene Klassen, da kann ja nicht mehr so viel schief gehen :lol:

Andreas :wink:

[igel457]

So, nachdem ich meine JavaScript, JQuery und AJAX Kenntnisse aus dem Keller geholt habe, habe ich nun die "Breadcrumb Bar" wie vorgeschlagen wurde um ausklappbare Menüs erweitert. Wichtig war mir persönlich, die Anzeigbarkeit ohne JavaScript und von Browsern wie Lynx/Links nicht zu beinträchtigen.

Ich hoffe das entspricht so euren Vorstellungen.

Auf dieser Seite ist der Effekt recht gut zu sehen:
http://andorracommons.sourceforge.ne...r.ProcessQueue

Andreas

Wichtig: Da ich nach wie vor noch keine Übersichtsseite für die Units habe, zeigt das erste Menü nur leeren Inhalt an.

[igel457]

So, das Ganze könnte zwar noch endlos erweitert werden, aber ich denke es ist außerdem recht brauchbar. Außerdem möchte ich nun meine Dokumentation verbessern und nicht meine Zeit damit verschwenden ein System für die Dokumentation zu schreiben.

Also habe ich das Ganze "Version 1.0" genannt und es veröffentlicht. Zu finden ist es hier, Anleitung ist im Paket.

Bitte beachten, dass ich das Ganze nur mit FPC unter Linux getestet habe und ich Windows und Delphi nicht offiziell unterstütze!

http://sourceforge.net/projects/andorracommons/files/

Nochmal der Link zur Andorracommons Doku:
http://andorracommons.sf.net/docs/

Für Vorschläge bin ich weiter offen,
Andreas