PHP-Entwicklung

PHP-Entwicklung

Posts 1-10 of 12
  • Dr. Daniel Pozzi
    Dr. Daniel Pozzi    Premium Member   Group moderator
    The company name is only visible to registered members.
    Handbuch aus Quellcode generieren?
    Hallo.

    Gibt es irgendein Tool, mit dem man Fließtexte für Endnutzer zusammenführen kann, um daraus ein Handbuch o.ä. zu machen? Bei nem privaten Projekt würde ich gerne Erklärungen zu den Klassen schreiben, anstatt separat die Doku zu pflegen. Ich meine jetzt nicht das klassische JavaDoc mit zb PHPDocumentor, sondern eher sowas:

    <?php

    /*
    * Klasse XYZ
    * @author Daniel
    * @package blabla
    * @handbookElement Markdown:/somechapter/somesection/somesubsection/
    */
    XYZ
    -----
    Lorem ipsum dolor sit amet, consetetur sadipscing elitr, sed diam nonumy eirmod tempor invidunt ut labore et dolore magna aliquyam erat, sed diam voluptua. At vero eos et accusam et justo duo dolores et ea rebum. Stet clita kasd gubergren, no sea takimata sanctus est Lorem ipsum dolor sit amet.

    */


    Kennt da jemand was praktisches?
    • 18 Jun 2009, 4:48 pm
  • Roland Wilczek
    Roland Wilczek    Premium Member
    The company name is only visible to registered members.
    Re: Handbuch aus Quellcode generieren?
    wie wäre es mit
    /*
    * Klasse XYZ
    * @author Daniel
    * @package blabla
    * @tutorial tutorialName
    */

    Dokumentiert unter:
    http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocume...

    Zwar pflegt man diese Tutorials in DocBookXML separat von den Quelltexten (womit der Einsatz für private Projekte wohl meist oversized erscheint), aber was besseres kenne ich nicht.
    This post was modified on 18 Jun 2009 at 05:05 pm.
    • 18 Jun 2009, 5:02 pm
  • Dr. Daniel Pozzi
    Dr. Daniel Pozzi    Premium Member   Group moderator
    The company name is only visible to registered members.
    Re^2: Handbuch aus Quellcode generieren?
    Ja, das hab ich mir mal angesehen. Dann muss jeder Mitstreiter auch noch DocBook lernen. Bringt das im professionellen Einsatz überhaupt nen MEhrnutzen?
    • 18 Jun 2009, 5:09 pm
  • Roland Wilczek
    Roland Wilczek    Premium Member
    The company name is only visible to registered members.
    Re^3: Handbuch aus Quellcode generieren?
    Dr. Daniel Pozzi schrieb:
    Bringt das im professionellen Einsatz überhaupt nen MEhrnutzen?
    das muss jeder selbst wissen. Wenn "professioneller Einsatz" heisst, unter Zeitdruck zu hacken und Doku eh' hintanzustellen, dann sicher nicht.

    Wenn aber eine wirklich gute Doku erstellt werden soll und die rein technische Inline-Dokumentation nach phpDoc-Standard nicht reicht, dann sind die phpDoc-Tutorials schon sehr gut. Denn sie verbinden auf fast unschlagbare Weise die DocBook-Dokumente mit der technischen Dokumentation (per Hyperlinks, auf Wunsch auch bidirektional).

    Nur muss man beachten, dass diese Tutorials manuell geschrieben und gegliedert werden müssen. Unter Zeitdruck wird so eine Doku schnell zur Lügensammlung.
    • 18 Jun 2009, 5:30 pm
  • Harald Lapp
    Harald Lapp    Premium Member
    The company name is only visible to registered members.
    Re: Handbuch aus Quellcode generieren?
    hallo,

    wir benutzen robodoc zur quellcode-dokumentation und schreiben damit durchaus auch ausführliche erklärungen und code-beispiele:

    http://www.xs4all.nl/~rfsber/Robo/robodoc.html

    vorteile gegenüber phpdoc:
    - es ist sprach-neutral
    - daraus ergibt sich eine einheitliche dokumentation, egal ob ich javascript, php oder die doku eines shell-scripts vor mir habe
    - das ganze ist einigermassen flexibel konfigurierbar

    nachteile:
    - mehr schreibaufwand als z.b. phpdoc, da der quellcode an sich nicht analysiert wird
    - keine integration z.b. in eclipse oder andere IDEs

    gruss,
    harald
    • 18 Jun 2009, 8:41 pm
  • Roland Wilczek
    Roland Wilczek    Premium Member
    The company name is only visible to registered members.
    Re^2: Handbuch aus Quellcode generieren?
    Unterstützt denn robodoc auch die code-completion von IDEs wie ZendStudio etc.? Denn diese wertet phpDoc-Annotationen aus.
    Oder muss man dafür die Kommentare redundant pflegen?
    Also etwa:

    /****m*
    * INPUTS Foo $foo Kommentar zu Parameter
    * OUTPUT Bar
    *
    * @param Foo $foo Kommentar zu Parameter
    * @return Bar
    */
    public function BarForFoo(Foo $foo);

    Das wäre ja nicht so schön, denn auf Code-completion würde ich nicht mehr verzichten wollen.
    This post was modified on 18 Jun 2009 at 09:32 pm.
    • 18 Jun 2009, 9:31 pm
  • Harald Lapp
    Harald Lapp    Premium Member
    The company name is only visible to registered members.
    Re^3: Handbuch aus Quellcode generieren?
    hallo,

    wie gesagt ... das ist ein nachteil von robodoc, oder evtl auch ein nachteil von eclipse / PDT, dass man das nicht ohne weiteres umrüsten kann. andererseits kann man in eclipse ja recht einfach code-templates anlegen und die code-blöcke darüber einfügen. das einzige problem ist halt weiterhin, dass man keine doku der funktionen in eclipse hat.

    btw.: afaik geht auch die code-completition für phpdoc nicht komplett, bzw. nur über einen trick: wenn man nämlich ein objekt als return-value einer methode zurückliefert. da php (noch) kein type-hinting für return values unterstützt, hat es sich da nämlich dann mit der code-completion.

    ansonsten ist das halt eine abwägungssache: uns war es wichtiger ausführlichere dokumentation im quell-code zu haben, eine einheitliche dokumentation über alle sourcen des projekts generieren zu können und dokumentation zu schreiben, die einheitlich für jede eingesetzte programmiersprache ist.

    gruss,
    harald
    This post was modified on 19 Jun 2009 at 08:24 am.
    • 19 Jun 2009, 08:16 am
  • Roland Wilczek
    Roland Wilczek    Premium Member
    The company name is only visible to registered members.
    Re^4: Handbuch aus Quellcode generieren?
    Harald Lapp schrieb:
    hallo,
    btw.: afaik geht auch die code-completition für phpdoc nicht komplett, bzw. nur über einen trick: wenn man nämlich ein objekt als return-value einer methode zurückliefert. da php (noch) kein type-hinting für return values unterstützt, hat es sich da nämlich dann mit der code-completion.
    Das ist richtig. Dokumentiert man einen scalaren Typ, resource oder array als Rückgabetyp, kann es keine Code-Completion geben, da diese Typen ja keine Schnittstelle besitzen.

    Bei unklaren Typen kann man sich zumindest bei ZendStudio allerdings helfen:

    class Foo
    {
    ../**
    ...* @return array von Foo-Objekten
    ..*/
    ..public function getObjects() { /* returniere ein Array von Foo-Objekten */}
    }

    $foo = new Foo();
    foreach ($foo->getObjects() as $object) { // keine IDE kennt den Typ von $object
    ../* @var $object Foo */ // <------------------- mit der Inline-Dokumentation des Typs allerdings schon!
    ..$object-> // ... jetzt liefert die IDE hier Code-Completion
    }
    • 19 Jun 2009, 11:21 am
  • Post visible to registered members
  • Ferdinand Kestennus
    Ferdinand Kestennus
    The company name is only visible to registered members.
    Re: Handbuch aus Quellcode generieren?
    Hallo,

    es kommt wohl darauf an, was das "Handbuch" dokumentieren soll. Bei "Endnutzer" würde ich ein "Benutzerhandbuch" darunter verstehen.

    Die im Quelltext erstellten "Dokus" dienen wohl eher dazu, einem Programmierer das "Gedankengut" des Code-Entwicklers zu erläutern, also mehr eine "Systemdokumentation".

    Der Gedanke, aus der Entwicklung einer Software heraus gleichzeitig ein Benutzerhanduch zu erstellen, ist ja nicht neu. Allerdings ergibt sich ein Benutzerhandbuch nicht aus der technischen Umsetzung, sondern mehr aus der Analyse der Anforderungen. Dort sind dann auch die verschiedenen Szenarien erkennbar.

    Von daher ergibt sich aus der ordentlichen Dokumentation der Anforderungen automatisch auch ein Benutzerhandbuch. Wichtig ist hierbei natürlich auch die Art der Anforderungsanalyse. Ein Vorgehen mit ICONIX führt nach meinen Erfahrungen zu guten Ergebnissen. Wenn man hier bspw. konsequent mit Powerdesigner oder vergleichbaren Instrumenten arbeitet, entsteht zwangläufig auch ein brauchbares Benutzerhandbuch.

    MfG

    Ferdinand Kestennus
    • 19 Jun 2009, 12:45 pm