Plsqldoc Genereer je documentatie
Beeklaan 444 2562 BK Den Haag www.darwin-it.nl
[email protected] KvK 27283780 ING 65.35.40.663
Martien van den Akker Technical Architect Net als (vrijwel) elke ontwikkelaar vind ik het documenteren van mijn software een noodzakelijk kwaad. Het moet gebeuren, maar het is oer-vervelend. En wat moet je dan documenteren? Hoe ver moet je gaan? En wat een gedoe als je een parameter toevoegt of verwijdert. Wat is het dan toch makkelijk als je net als bij java van je pl/sql-code de documentatie kunt genereren. En dat kan! Maar dan wel met Pl/Sql Developer. Veel collega's denken nu natuurlijk: daar heb je die van den Akker weer met zijn Pl/Sql Developer. Sorry, jongens, maar voor Pl/Sql Developer is een plug-in die bovenstaande nu net kan. Deze kun je downloaden van de site van Allround Automations, naast een hoop andere, erg handige, plugins: http://www.allroundautomations.nl/plsplsqldoc.html.
Om te beginnen De plug-in is heel eenvoudig te installeren met een setup-programma. Waarna je een aantal menu opties in het tools menu er bij krijgt.
Afbeelding 1: Plsqldoc sub menu Wel handig is dat deze opties ook als button voor de knoppenbalk beschikbaar zijn. Configureren is eigenlijk ook heel eenvoudig: het belangrijkste is even aangeven waar je de documentatie gegenereerd wil hebben. In een project omgeving zul je daarvoor een netwerkschijf voor kiezen:
Afbeelding 2: Plsqldoc configuratie Voor de rest is het zaak dat je het commentaar in je code op de juiste manier opmaakt. Een voorbeeld hiervan is het volgende stukje package specificatie: create or replace package xxx_clients is / *************************************************************************************** **** Package to retrieve Client-information from TCA module and package it into ObjectTypes #Version 0.1 #Author Martien van den Akker #Usage Fetch clients-information from TCA
Change History When Who: What
- 14-sep-2004 Martien van den Akker: Initial Creation
*************************************************************************************** *****/ -- Constant for address type 'Mail-address' g_adress_type_mail varchar2(30) := 'POST'; -- Constant for address type 'Home-address' g_adress_type_home varchar2(30) := 'HUIS'; -- Constant for address type 'Billing-address' g_adress_type_bill varchar2(30) := 'BILL_TO'; / *************************************************************************************** **** Returns address of type address_type of a party from TCA #Version 0.1 #Author Martien van den Akker #Usage #param party_id #param p_address_type
TCA Party_id: Id of the client Type of the address to be fetched
#value p_address_type
{*}{#link xxth_clients.g_adress_type_mail} {*}{#link xxth_clients.g_adress_type_home} {*}{#link xxth_clients.g_adress_type_bill} #return {#link xxth_address_t} *************************************************************************************** *****/ function f_get_address( p_party_id in number , p_address_type in varchar2) return xxx_address_t;
Wat opvalt is dat er een combinatie van html en voorgedefinieerde tags mogelijk zijn. Wanneer een declaratie van een variabele, type, functie of procedure (eigenlijk elke vorm van Pl/Sql declaratie) voor af gegaan wordt door een stuk commentaar dan beschouwd plsqldoc dit als beschrijvend voor die declaratie. Daar in kunnen nog extra tags worden opgenomen. Hier onder een overzicht van mogelijke tags: Tag
Beschrijving
#param
Een beschrijving van de parameter van een functie of procedure. Op een volgende #param tags worden in tabel geplaatst. . #return
Een beschrijving van de return waarde van een functie.
#value Een mogelijke waarde van een package variable, procedure/functie parameters of object type attribuut. Op een volgende #value tags worden in tabel geplaatst. . #raises Een lijst van excepties die door een program unit kunnen worden gegenereerd. Zie ook hyperlink. Op een volgende #see tags worden in een tabel geplaatst. Wanneer naar een specifieke overloading of een program unit moet worden verwezen, laat de naam can volgen door een punt-comma en een overload #see #see employee #see department.dname;2 #usage
Een beschijving van het gebruik van het object
#author De auteur van het object. #version De versie van het object. {#link [description]}
Een expliciete hyperlink.Wanneer naar een specifieke overloading of een program unit moet worden verwezen, laat de naam can volgen door een puntcomma en een overload index (1-based). De optionele beschrijving wordt geplaatst in het document. Bijvoorbeeld:
or
The {#link department.name department name function} is...
{#link [description]}
resulteert in: The department name function is...
Een bullet of een bullet list. Bruikbaar voor het beschrijven van mogelijke waarden van een parameter of return waarde. Bijvoorbeeld: {*}
{#skip}
{*} 0 The function returned successfully {*} 1 The employee does not exist {*} 2 The employee record is locked Sla dit comment block over voor documentatie.
Genereren van documentatie De documentatie kan bijvoorbeeld gegenereerd worden vanuit het context menu, of het menu. Je kunt ook meerdere objecten uit de browser selecteren en daar in een keer documentatie voor genereren:
Afbeelding 3: Context menu De gegenereerde documentatie kan worden bekeken vanuit de Pl/Sql Developer interne browser, maar is natuurlijk ook op een webserver te zetten of netwerk-share om met een willekeurige browser (bijvoorbeeld Mozilla/Firefox):
Afbeelding 4: Index van Plsqldoc De documentatie die zo gegenereerd wordt is eigenlijk een soort van web-site waar je door heen kan klikken. Het deed mij wel wat denken aan de Repository Object Browser van Designer (of voor de oudgedienden: "Cherry-pie" van designer 1.3.2). Maar dan gegenereerd op basis van je commentaar in je package. Erg prettig is ook dat plsqldoc alles genereert op basis van een cascaded style sheet (CSS). Door alleen dit stijlen-bestand te bewerken, kun je de look van de hele documentatie aanpassen aan je bedrijfs-huisstijl. Misschien een leuke klus voor de Designer/ Developer community: een Headstart plsqldoc-stylesheet maken? De documentatie van het stukje voorbeeld package aan het begin ziet er overigens als volgt uit:
Afbeelding 5: Documentatie van een package specificatie
Afbeelding 6: Documentatie functie declaratie
Conclusie Voor Pl/Sql Developer zijn er blijkbaar erg handige plug-ins waarvan het hier en daar de moeite loont ze te bekijken. Plsqldoc is echt een briljantje. Erg netjes gemaakt en voor iemand die regelmatig met pl/sql klust erg prettig. De gegenereerde documentatie is zo op te leveren. Als je overigens aan tabellen en views en bijbehorende kollommen comments toevoegt (comment on table tabel/view-naam is 'commentaar' of comment on column kolom-naam is 'commentaar' ), kun je daarvoor ook documentatie genereren! Veel plezier ermee! Martien van den Akker Development specialist
