Contao API & DCA Dokumentation

Was haltet Ihr davon im contaowiki eine umfassende Dokumentation von der contao core API und DCA Funktionsweise zu erstellen?

Ich habe bei der Entwicklung schon mehrmals festgestellt, dass die Informationen auf http://www.contao.org/dca.html, für mich, nicht genug ausführlich sind. Es werden, da Aspekte vom DCA erwähnt. Allerdings gibt es keine illustrativen Codebeispiele und Funktionsbeschreibungen (Type, Parameter, ...).
Zudem fehlt mir bis jetzt eine zentrale Dokumentation, die zeigt wie ich mit dem contao core entwickeln kann. Das Buch (contao für Entwickler) ist da ein guter Ansatz, jedoch m.E. zu wenig ausführlich, und eben nicht online ;) Die phpDoc generierte API bringt nicht viel, da die Funktionen nicht beschrieben werden. Bei manchen Modulen ist auch in der config.php Beispiel-PHP-Code auskommentiert.

Ich schlage deshalb vor eine zentrale und offizielle Dokumentation mit Codebeispielen des der contao core API und DCAs im contaowiki zu erstellen. Was meinst Ihr dazu?

Da kann ich nur sagen : Fang doch einfach an ;-)

@lindesbs!

Da kann ich nur sagen: Wann bist Du fertig? ;-)

Freundliche Grüße
Frank

@frank : ich koennte sagen, "it is done, when its done".

Aber auch das wird fertig. UNd die Doku wird dann auch veroeffentlicht.

24 hours are not enough

@lindesbs

Dankeschön. :)

Freundliche Grüße
Frank

Also ich entnehm euren Antworten, dass ihr sowas auch begrüssen würdet. Ich wollt eben nicht einfach mal anfangen irgend etwas aufzusetzen. Sinn und Zweck wäre ja später einmal die bisherige offizielle Dokumentation abzulösen. Deshalb dacht ich mir mal hier bei den Verantwortlichen nachzufragen, ob dies den überhaupt gewünscht ist? Wenn ja, bin ich gern bereit da mal einen Anfang zu machen.

Hallo,

die Ideee finde ich großartig. Gerne würde ich mich dafür anbieten, allerdings bin ich selber PHP-Anfänger und gerade erst bei OOP angekommen :o.

Ein Aufbau wie bei php.net wäre toll.

Schönen Abend noch!

varix

Ich hatte Leo vor einigen Monaten auf das Thema angesprochen, und er hat gesagt ich könnte mich gerne darum kümmern, wenn ich Zeit dazu habe. Leider ist daraus nie etwas geworden...

Aus meiner Sicht müssten wir erst einen Standard für die Doku finden, php.net finde ich auch sehr gut, aber ich weis nicht ob das für OOP geeignet ist.

Zitat:

---

Aus meiner Sicht müssten wir erst einen Standard für die Doku finden, php.net finde ich auch sehr gut, aber ich weis nicht ob das für OOP geeignet ist.

---

Die Aufteilung nach:

### Beschreibung ###

### Parameterliste ###

### Rückgabewert ###

### Weiters ###

fände ich für Funktionen schon mal gut. Das sollte sich im Wiki auch gut darstellen lassen. Komplizierter wird es hier schon bei den DCA's. Jemand ne Idee? Mir fällt gerade kein gutes Beispiel ein.

Gruß Felix

php.net find ich auch nicht schlecht. Vor allem ist wichtig, dass die API durch User Kommentare ergänzt werden kann.
Mit Tools wie phpDocumentor (Beispiel output: http://manual.phpdoc.org/HTMLframesConverter/phpedit/) könnte man sicher eine gute Dokumentation erstellen. Allerdings wären da soviel ich weiss keine Benutzer Kommentare möglich. Dafür wäre das wiki schon gut. Wie es aussieht ist der phpDocumentor Output aber nicht ohne Weiteres ins Wiki integrierbar (siehe http://stackoverflow.com/questions/6...mentor-to-wiki).
Um den DCA zu Kommentieren könnte man ein XSD definieren, und aufbauend auf dem dann die Dokumentation in XML erstellen. Mit XSLT sollte es dann möglich sein das ganze in wiki Syntax zu transformieren.

Edit: Ein weiteres vielversprechendes Tool wäre Doxygen (Beispiel Output: http://drupal-6-doxygen.engineeredweb.com/), natürlich wieder mit verzicht auf Benutzerkommentare.

Ich bins nochmal :) Vielleicht wäre es auch sinnvoll zwei Dokumentationen zu erstellen...

1. Automatisch generierte API Dokumentation (mit Doxygen?) der contao core Klassen. (Database, Module etc.). Mit kurzen Codesnippets wo sinnvoll.
2. Wiki Dokumentation für Hook und DCA Konfiguration.

Was meint Ihr?

Ich hatte mir dei verfügbaren Tools eigentlich angesehen, aber leider ist keines davon wirklich genügend. Eine reine API-Doku ist auch nicht wirklich ausreichend, und wir können ja nicht von Leo verlangen dass die ganze Doku in den Core-Code kommt.

Ich denke schon das man in sowohl in phpDoc als auch in Doxygen ein Kommentarmodul einbauen kann! Man muss sich Templates bauen die entsprechenden PHP-Code enthalten.

Das größere Problem sehe ich hier in der Beschreibung IM Quelltext wo kein Platz für größere Beispiele etc. ist. Vllt lässt Doxygen hier Workarounds über die Doxytags zu:
http://www.stack.nl/~dimitri/doxygen/external.html


## Edit
Ein Kollege hat vor längerem ein phpDoc Template aufgebohrt um per einfachem PHP-Include Wiki-Artikel entsprechend des Namespaces in die API-Dok zu inkludieren.
Wie ich das verstanden habe gabs im Wiki Artikel wie "Class/System", dieser wurde dann im phpDoc bei der Klasse System eingebunden. Ähnlich für Methoden "Class/System/Method".

Zitat:

---

Das größere Problem sehe ich hier in der Beschreibung IM Quelltext wo kein Platz für größere Beispiele etc.

---

http://www.stack.nl/~dimitri/doxygen...cturalcommands
Die Kommentare könnten also extern angebracht werden. Allerdings fehlt dann die Dokumentation beim Source-Code. In IDEs werden dann die Code-Hints nicht mehr angezeigt... Und dem Entwickler fehlt die Dokumentation im Code, er müsste immer die externe Doku konsultieren. Auch nicht das gelbe vom Ei.

Man könnte aber einfach die Beschreibung, Parameter, Returns etc. direkt im Source angeben, wie üblich. Und dann einen externen Link angeben zur ausführlicheren Dokumentation im Wiki. Die Templates könnte man immer noch modifizieren, um Inhalte (Code Beispiele etc.) aus dem Wiki nach zu laden.

Eine Inline-Doku finde ich nicht praktikabel. 1: wir es schwer das mehrsprachig zu machen, 2. Sind wir dann von den Ressourcen von Leo abhängig - und der hat sicherlich schon genug zu tun.

Zitat:

---

Eine Inline-Doku finde ich nicht praktikabel

---

Damit meinst du eine minimale Dokumentation der Methoden mit Beschreibung und Parametern wäre nicht gut? Ich vermisse genau das zur Zeit. Ich finde auch, dass das Standard sein sollte, in jedem php Modul.

Zitat:

---

Sind wir dann von den Ressourcen von Leo abhängig

---

Wieso von Leo abhängig? Kann denn nicht jeder mithelfen die Kommentare im contao core zu vervollständigen?

Mehrsprachigkeit ist bei inline Doku ein Problem. Allerdings könnte man sich da auf Englisch einigen. Im Wiki kann die ausführliche Doku dann mehrsprachig sein.

Wie auch immer, es muss ein System her, wie die Doku geschrieben wird. Doxygen, Wiki, XML? Eine zentrale XML hätte den Vorteil, dass es mit XSLT in verschiedene Formate transformiert werden könnte ...

Zitat:

---

Zitat von bubblez

Wie auch immer, es muss ein System her, wie die Doku geschrieben wird. Doxygen, Wiki, XML? Eine zentrale XML hätte den Vorteil, dass es mit XSLT in verschiedene Formate transformiert werden könnte ...

---

Ganz meine Meinung, allerdings finde ich eine XML-Variante zu Zeitintensiv! Wer soll soll sich um Frontend und Backend für die Transformation kümmern? Ich nicht ... ;)

Ich halte ein Doxygen-Template was Inhalte aus dem Wiki zieht im Moment für am Zielführensten, da es mit überschaubaren Aufwand umzusetzen ist.

@andreas.schempp
Abgesehen davon, dass ich immer noch nicht verstehe, warum nicht jeder die contao core files kommentieren könnte ..., find ich die Idee die Dokumentation extern zu halten auch gut. Und wie oben erwähnt einfach möglich. Das schwierige dabei wird sein, Code und Doku konsistent zu halten... Was hältst du von dieser Idee?

Data Container Arrays und andere vordefinierte Array Strukturen von contao könnte man wie erwähnt mit XML definieren und mit XSLT dann in verschiedene Formate exportieren. Also auch in einen Wiki Dialakt wie markdown. Oder PDF oder HTML, oder Doxygen.

Zitat:

---

Ganz meine Meinung, allerdings finde ich eine XML-Variante zu Zeitintensiv! Wer soll soll sich um Frontend und Backend für die Transformation kümmern?

---

Ja da hast du recht, die Transformation müsste dann jemand regeln oder automatisiert ablaufen ... XML fänd ich eben zukunftsweisend, denn man könnte dann soweit gehen und die PHP basierten config Files durch XML Dateien ersetzen. Dank XSD würde man dann direkt im Editor unterstützt (validierung, element-vorschläge).

Wenn wir XML weglassen und die DCA direkt im wiki Beschreiben, müsste man da einfach ein par Regeln finden, damit das dann auch einheitlich wird. Wie würden die wiki Seiten aufgebaut sein? Ganzer DCA auf einer Seite?

Vielleicht problematisch da es noch 1/2 Jahr dauert, aber was haltet ihr von einem Workshop an der Contao Konferenz? Da könnten wir uns 2h Zeit nehmen und Erfahrungen diskutieren. Ich werde das mal im entsprechenden Thread einbringen.

Wir müssten bei der Dokumentation auch zwischen den Klassen und dem DCA unterscheiden. Das DCA ist nicht schlecht dokumentiert, es fehlen nur einige Parameter und eher an effektiven Beispielen.
Die Core-Bibliotheken sind dagegen praktisch gar nicht dokumentiert. Ausserdem fehlen Informationen zum Ablauf (z.B. URL act=edit triggert DC_Table::edit()), aber die sind schwer in ein Standardformat zu bringen.

Den Workshop zum Thema finde ich eine gute Idee. Bis dahin können sicher noch einige Ideen weiter ausgebaut werden und dann auch entsprechend präsentiert werden.

Zitat:

---

Wir müssten bei der Dokumentation auch zwischen den Klassen und dem DCA unterscheiden. Das DCA ist nicht schlecht dokumentiert, es fehlen nur einige Parameter und eher an effektiven Beispielen.

---

Unterscheidung zwischen Klassen und DCA auf jeden Fall, deshalb auch die Idee mit Doxygen und wiki/xml. Was den DCA betrifft, wäre es meiner Meinung nach eben sinnvoll die ganze Dokumentation aufzufrischen und alles an einen Ort (sinnvollerweise das wiki) zu transferieren. So könnte dann auch die generierte Doxygen Dokumentation auf Inhalte aus dem wiki verweisen.

Workshop tönt gut :) Vielleicht gibt es Leute die da gute Inputs bringen könnten.

Funktionaler Mockup unter: http://code.contaowiki.org

Fehlt noch die BBCode Auszeichnung und der Sync mit dem ER Server, aber das kommt noch.

Login mit den "normalen" Zugangsdaten des Wikis.

Gruss
Chris

Hi,

sei doch bitte so gut und erkläre kurz was hier jetzt alles gemacht werden muss? Ich bin mir noch nicht ganz im Klaren darüber. (Bin ich da der einzige?)

Gruß Felix

Bislang "muss" noch nichts gemacht werden, da ich aktuell noch daran sitze, den kompletten Import fertigzustellen.

In naher Zukunft muss man jedoch dann sich wie bei php.net hinsetzen und Beschreibungen verfassen.

Aktuell importiere ich alle Klassen, deren Funtionen, parameter, Properties usw. und den jeweilig zugehoerigen phpdocComment (sofern vorhanden).

Anschliessend kann man die Seiten kommentieren und als angemeldetes Mitglied auch bearbeiten/ybersetzen.

Jedoch muss ich wie gesagt noch den import fertig stellen, bzw. dahingehend abaendern dass er nicht alles wieder bygelt, bevor ich euch darauf loslassen kann. :)

Es ist bislang noch ein mockup, welchen ich gestern im IRC gezeigt habe und euch hier nun auch nicht vorenthalten wollte.

Eine Anbindung/Vernetzung/Integration von ER und contao-forge.org ist weiterhin angedacht.

Gruss
Chris

Ich fänd es gut, wenn man die Beschreibungen einer Klasse UND dessen Props/Methoden/Konstanten/... auf einer Seite einsehen könnte, die mit internen Links hin- und her referenziert. Javadoc macht das so und ich find das x-mal praktikabler als php.net (soll nicht heißen das php.net Mist ist).
Das soll natürlich kein Ersatz sein, weil die Kommentare zu den einzelnen Methoden müssen ja auch irgendwo hin.

Finde ich auf jeden Fall einen guten Ansatz. Danke Für die Erklärung ;)

*push*

wie ist denn eigentlich hier der aktulle stand der dinge, bzw gibt es einen aktuellen stand überhaupt? ;)

könnte man hier schon mit befüllen/ergänzen anfangen ?

Gesehen habe ich da schon was, kann aber nicht sagen wie weit xtra ist.

Hallo.

Ich differenziere jetzt mal zwischen DCA-Dokumentation und API-Dokumenation:

DCA-Dokumenation

Gibt es schon Ansätze für eine DCA-Dokumentation?

Ich meine, es ist schön, wenn es eine API-Dokumentation gibt die automatisch generiert werden kann, jedoch ist das meines Erachtens mit DCA nicht möglich, da es sich nur um verschachtelte Arrays handelt, woraus sich schwierig irgend eine Dokumentation generieren lässt.

Ich stehe derzeit auch vor dem Problem, dass ich die Dokumentation für DCA als nicht ausreichend erachte, da einige Dinge fehlen (zb Bezeichung von den 'Core-Array-Feldern') und keine Codebeispiele vorhanden sind. Klar, kann ich von vorhandenen Modulen etwas abschauen, jedoch ist das für mich keine Dokumentation, mit der ich alles im Blick habe, und wo ich sehe, welche Möglichkeiten/Einstellungen das es noch gibt.

Die DCA-Erklärung im Entwicklerhandbuch ist eher als Übersicht zu sehen, aber für einen Entwickler sind diese Informationen einfach zu High-Level und ungenau.

Kann man mit einer DCA-Dokumentation rechnen?


API-Dokumentation

Den Ansatz die Dokumentation in den Code einzubauen, halte ich für sinnvoll. Das Argument dass es hier nicht möglich ist, wegen der Mehrsprachigkeit der Dokumentation kann ich nicht gelten lassen, denn wenn der Code in Englisch geschrieben wird und die Dokumentation in Englisch ist, ist es meines Erachtens ausreichend, da ich grundlegende Englischkenntnisse bei jedem Entwickler vorraussetze.

Ich finde, wer einen vernüftigen Code schreiben will, muss auch vernünftig dokumentieren, damit der Code für jeden verständlich ist.

Gruß,
mangei

Die DCA-Dokumentation ist hier: http://www.contao.org/entwicklerhandbuch.html

Hallo Andreas,

ich habe das Entwicklerhandbuch natürlich bereits studiert ;)

Ich finde das für einen ersten Überblick ganz gut, aber wenn ich dann genau wissen will, wie ich eine TextArea erstellen kann und welche Einstellungen das für diese möglich sind, im gegensatz zu einer Checkbox, wo es andere Einstellungen gibt, finde ich diese Dokumentation ein wenig ernüchternd.

Wenn ich dann aber sehe, ok, es gibt Tabellenkonfigurationen und Aktionen, welche sich in globale und reguläre Aktionen aufteilen, fragt man sich natürlich: Ok, und wie schreibe/setzte ich all diese Attribute und wie sieht die Datenstruktur aus?
Es ist mir leider nicht ersichtlich das es dort allgemeine Fields wie "config, list, global_operations, operations, etc." gibt und wie diese aufgebaut sind.

Wenn ich die Datenstruktur im ff habe und nur nachsehen möchte, wie ein Attribut heist, ist das natürlich ausreichend, doch für Entwickler die sich nicht täglich mit dieser Materie auseinandersetzten ist das leider wenig aussagekräftig.

Gruß,
Manuel

Hallo zusammen,

mal eine (vielleicht) doofe Frage:

Tut sich auf api.contao.org bezüglich der Anzeige der Dateiinhalte irgendwann noch etwas? Vielleicht habe ich das auch einfach nur überlesen. Oder ist es etwa gewollt, dass ich die Dateien nicht direkt einsehen kann. Das würde schon vieles vereinfachen. Vor allem wäre es nicht so verwirrend, wenn man auf einen Link à la (line 47) klickt und nichts passiert.

Ansonsten "Hut ab", alles schön übersichtlich und strukturiert - tausendfach besser als die erste Version!