Data driven documentation für PL/SQL Daniela Reiner Consultant daniela.reiner@trivadis.com Stuttgart, 14.05.2009 Basel Baden Bern Brugg Lausanne Zürich Düsseldorf Frankfurt/M. Freiburg i. Br. Hamburg München Stuttgart Wien
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 2
Was ist Data Driven Documentation? Dokumentation wird aus Kommentaren im Quellcode generiert. Parallel zur Entwicklung Gleichzeitig Quellcodedokumentation Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. Aktuelle Daten JavaDoc Data driven documentation for PL/SQL 3
Java API-Documentation Data driven documentation for PL/SQL 4
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 5
Welche Tools für PL/SQL gibt es? PLDoc Open Source nicht mehr supportet Darstellung wie Javadoc Nur Packages Commandlineaufruf Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. DB Doc im SQL Developer Kontextmenü zur DB Quellcode + Metadaten PLSQLDoc Plugin für PL/SQL Developer Data driven documentation for PL/SQL 6
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 7
PL/SQL Doc Allgemeine Infos Plugin plsqldoc zum PL/SQL Developer (www.allroundautomations.com/ plsqldev.html -> Plug-Ins) Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. Lizenzkosten PL/SQL Developer Single User Lizenz 180 US$ Staffelpreise Plugin kostenlos Darstellung Dokumentation im HTML- Format Steuerung über Menüführung Toolbar Kontextmenü Command-Window Data driven documentation for PL/SQL 8
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 9
PL/SQL Doc Funktionen Kommentare Strict comments /** */ Non strict comments /* */ -- Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. Kommentar im Quellcode theoretisch beliebig vor create nicht in DB nach begin evtl. zu lang nach is keine Probleme Data driven documentation for PL/SQL 10
PL/SQL Doc Funktionen HTML-Befehle zur Formatierung Zusammenfassung (synopsis) Allgemeine Beschreibung Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. Tags Strukturierung vorgegeben oder selbst definiert maximal drei zusätzliche Tags in Konfiguration (mehr in ini-datei) Tag-einleitende Zeichen @ % # Data driven documentation for PL/SQL 11
Tags param return raises author version usage value see link skip Parameter einer Funktion oder Prozedur Rückgabewert einer Funktion Beschreibung des Exception-Blocks Verfasser / Erzeuger eines Objekts Version eines Objekts Sinn und Zweck eines Objekts Werteliste für beliebige Objekte Verweis auf Seite in Dokumentation oder Web Link in einem Text auf Seite in Dokumentation oder Web mit alternativem Anzeigetext Aktueller Kommentar wird ignoriert Data driven documentation for PL/SQL 12
Konfigurations-Dialog Data driven documentation for PL/SQL 13
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 14
PL/SQL Doc Darstellung Interner Browser im PL/SQL Developer Index mit oder ohne Frames Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. CSS Name von CSS-Datei beibehalten Kategorien beibehalten, sonst Default Beispiel Data driven documentation for PL/SQL 15
Agenda Was ist Data Driven Documentation? Welche Tools gibt es? Daten sind immer im Spiel. PL/SQL Doc Allgemeine Infos Funktionen Darstellung Fazit Data driven documentation for PL/SQL 16
Fazit Das Mass unserer Dinge ist die Höhe Ihrer Ansprüche. Vorteile PL/SQL Doc Verschiedene Datenbankobjekte Viele Konfigurationsmöglichkeiten Anpassung mit CSS HTML-Befehle im Quellcode Batchbetrieb (Command-Window) Vielfältige Bedienung Tags sind erweiterbar Einheitliche Darstellung Nachteile PL/SQL Doc Nur mit PL/SQL Developer Nicht alle Funktionen laufen korrekt Kein Quellcode integriert Data driven documentation for PL/SQL 17
Vielen Dank!? www.trivadis.com Basel Baden Bern Brugg Lausanne Zürich Düsseldorf Frankfurt/M. Freiburg i. Br. Hamburg München Stuttgart Wien