[Suche] Wiki für Source-Code / Source-Code Dokumentation

[fkerber]

Hi!

Sorry für die Überschrift, aber ich wusste nicht, wie ich es besser beschreiben sollte.

Also, um was es mir geht:
Ich stehe vor der Aufgabe, ein größeres PHP-Projekt komplett neu zu programmieren und möchte es dabei auch ordentlich dokumentieren. Dabei kam mir spontan folgende Idee:
Vllt. gibt es ja ein Wiki, dass automatisch einen Ordner "monitored" und automatisch Wiki-Einträge vorsieht in denen ich a) direkt den Source-Code sehen kann und b) Kommentare dazu hinterlassen kann.
Dabei muss das Monitoring meinetwegen auch nicht so automatisch sein, also mir würde es auch reichen, wenn ich ein Wiki mit Quelltextdateien verknüpfen kann.

Daher meine Frage:
Gibt es so etwas oder vergleichbares?

Bzw. andere Frage:
Wie dokumentiert ihr solche Projekte?


Grüße, Frederic

[arbu man]

Ich dokumentiere im Quelltext mittels DocComment, das hat den Vorteil ich bin näher am Quellcode um muss nicht für jede Änderung der Dokumentation in eine Wiki/bzw. anderes System. Auch zeigt meine IDE diese Kommentare in der Codecompletion an.

Zusätzlich erstelle ich kommentierte Tests die zeigen wie die Komponenten meiner Software genutzt werden. Mit Kommentieren Tests meine ich das auch Zeilen oder Code Abschnitte Kommentare haben, wenn dies Hilfreich ist. Ein weiterer Vorteil ich bekomme mit wenn ein Test nicht mehr läuft, somit ist meine "Dokumentation" bzw. HowTo immer auf den neusten Stand und ich setze die Dokumentation nicht der Gefahr aus, das der in der Doku beschriebene Weg nicht funktioniert.

Zu guter Letzt verwende ich einen durchdachten und konsistenten Programmierstil der auch Analysen zulässt, beispielsweise kann ich mir eine .graphml-Datei generieren lassen die die Klassen Struktur meines Projektes aufzeigt. Diese Graphen tragen auch zu Dokumentation bei, sie beantworten Fragen wie:
Welche Klassen sind besonders wichtig/werden oft benutzt ?
In welchen Klassen wird meine Klasse xy verwendet ?
usw.

Prinzipell sehe ich bei Systemen die nicht in der IDE integriert sind immer die Gefahr das diese Schlect/Nicht benutzt werden.

Um nochmal auf deine Frage zurückzukommen im Grunde macht der phpDocComment genau das was du willst, er ist nur kein eigenes System, was ich besser finde. Es gibt aber Software die aus dem phpDocComment eine Webseite generiert.

Gruß Björn

[fkerber]

Hi!

Danke für deine Antwort.
Aber ich habe mich wohl oben schlecht ausgedrückt, sorry.
Also es geht mir nicht um eine Dokumentation des Quellcodes im Sinne von Kommentaren, wie sie ein anderer Programmierer lesen will, sondern es soll mehr in Richtung Dokumentation des Projektes gehen, wie sie ein Anwender lesen will, aber eben unterteilt nach den einzelnen "Klassen"/Dateien. Also mehr Hilfesystem als Quellcode-Kommentare.


Grüße, Frederic

[Luckie]

Zitat:

Zitat von fkerber

es soll mehr in Richtung Dokumentation des Projektes gehen, wie sie ein Anwender lesen will, aber eben unterteilt nach den einzelnen "Klassen"/Dateien. Also mehr Hilfesystem als Quellcode-Kommentare.

Sollte sich eine Hilfe für Anwender nicht her an der Oberfläche orientieren? Der Anwender hat doch keine Ahnung von den Klassen und Quellcodedateien und es dürfte ihn auch nicht interessieren. Was meinst du, wenn die Hilfe zu Word sich an den verwendeten Klassen orientieren würde, wie verständlich dann die Hilfe für den Endanwender wäre?

[fkerber]

Hi!

Nein, es soll keine Hilfe für den Anwender sein, sondern eine Dokumentation für den Anwender - in dem Fall ist Anwender aber nicht gleichzusetzen mit Nutzer des Systems. Ich hole etwas weiter aus. Es handelt sich um ein System, das später einen Admin hat (der nicht ich bin), der einen groben technischen Überblick bekommen soll, um auch mal etwas anpassen zu können oder ähnliches (z.B. an einem Template-System, das ja nur aus HTML besteht). Dafür sollen die einzelnen Sachen dokumentiert sein - das soll keine Bedienungshilfe für den Nutzer des Systems sein. Ich versuche es mal mit einem Beispiel (grad in Delphi).

Sei als Quelltext sowas gegeben (inkl. Kommentar für Programmierer etc)

Delphi-Quellcode:

procedure foo()
begin
  showmessage("bar");  // zeigt bar an
end;

Und dazu würde ich dann gerne einen Kommentar verfassen wie

Zitat:

Mit dieser Methode kann man dies und das machen. Dabei ist zu beachten, dass sie nur in diesem oder jenem Kontext aufgerufen werden darf und dabei die und die Nebenwirkungen hat.

Wenn ich das in die Quellcode-Datei reinschreibe finde ich das für denjenigen, der mit PHP dann nicht viel am Hut hat, nicht so komfortabel.



Grüße, Frederic

[arbu man]

Wer sich nicht mit php auskennt, wird wahrscheinlich auch nicht wissen was mit die "Funktion foo macht..." gemeint ist, da er wahrscheinlich nicht weiß was eine Funktion ist. Und wenn man nichts mit php macht nützt mir das Wissen was die Funktion foo macht auch nichts, da ich ja nichts programmiere wo ich das Wissen einsetzen kann. Von daher verstehe ich nicht was du genau willst.
Die Benutzer-Dokumentation unterscheidet sich stark von der Klassen Dokumentation. Daran wird man auch so schnell nichts ändern können da ein Benutzer das System nutzen will und es nicht programmieren will.

Wie gesagt beim phpDocComment kann man sich auch Html-Datei mit der Dokumentation generieren lassen.

LG Björn

[BUG]

Zitat:

Zitat von arbu man

Von daher verstehe ich nicht was du genau willst.

Wenn ich ihn Richtig verstanden habe, möchte er etwas bauen, was so etwas wie ein Wordpress-Theme ermöglicht. Dort sind PHP-Funktionen in HTML eingebettet (Bsp.), es wäre aber extrem lästig, diese erst in den entsprechenden Quelltexten nachzuschlagen => eine andere Art von Dokumentation ist nötig.

MfG,
Bug

[fkerber]

Hi!

@BUG:
Ja, in genau diese Richtung dachte ich.

Es liegt ein Template-System dahinter/davor ähnlich dem von PHPBB - d.h. es gibt tpl-Dateien (HTML-Dateien) die Sachen enthalten, die ersetzt werden (z.B. {ERROR_MESSAGE}).
Und da gibt es einfach Sachen, die jemand, der sich mit HTML auskennt, nutzen kann, auch wenn er von PHP keinen Plan hat und genau das soll hier ermöglicht werden. Sodass also gewisse Modifikationen ermöglicht werden und der Nutzer nicht ganz im Regen steht.

Ich glaube allerdings so langsam, dass ich es wohl doch selber schreiben muss, weil es nix in der Richtung gibt.


Grüße, Frederic