Geekly articles weekly

Création de code PL / SQL et génération de documentation PL / SQL (pldoc), similaire à JavaDoc

Au sein de l'équipe, vous devez développer vos propres normes et règles, et la paperasse est l'une des principales règles du travail d'équipe.

Eh bien, allons-y ...

Lien vers l'outil pldoc lui-même .

Par référence, tout est bien expliqué sur la façon de travailler et de générer de la documentation, mais pour vous faciliter la tâche, je vais donner des exemples et des scripts.

Installez (décompressez l'archive) et créez run.bat à la racine

rmdir /s /q "%TOMCAT_HOME%/Tomcat 7.0/webapps/plsqldoc" call ..\pldoc.bat -verbose -doctitle 'Api shema' -d '%TOMCAT_HOME%/Tomcat 7.0/webapps/plsqldoc' -url jdbc:oracle:thin:@host:port:SID -user API_DOC -password API_DOC -sql SCAPI.%%%%,API.%%%%,SALE.%%%%,BILLING_API.%%%%,BATCH.%%%%, pause

où:

  • -d '% TOMCAT_HOME% / Tomcat 7.0 / webapps / plsqldoc' - le dossier où la documentation sera générée;
  • -url jdbc:oracle:thin:@host:port:SID serveur de base de données jdbc:oracle:thin:@host:port:SID où jdbc:oracle:thin:@host:port:SID les données;
  • -sql API. %%%% T %%%%, SALE.A %%%%, BILLING_API. %%%%
    API. %%%% T %%%% - prend tous les objets de schéma d'API contenant la lettre T;
    SALE.A %%%% - prenez tous les objets du schéma SALE en commençant par la lettre T;
    BILLING_API. %%%% - prend tous les objets du schéma BILLING_API;

Nous commençons et obtenons la documentation finie, selon les règles de conception du code pl / sql décrites ci-dessous.

Exemple de conception


Règles d'inscription .
Règles d'inscription .

Pour les packages

 create or replace package EXAMPLE is -------------------------------------------------------------------------- -- ELEMENT PREFIX SUFFIX EXAMPLE DESCRIPTION -------------------------------------------------------------------------- -- variable v_ # v_club# All variables have to start with "v_" ends with "#" in lowercase -- in parameter in_ # in_club# All in parameters have to start with "in_" ends with "#" in lowercase -- out parameter out_ # out_club# All out parameters have to start with "out_" ends with "#" in lowercase -- in/out parameter io_ # io_club# All in/out parameters have to start with "io_" ends with "#" in lowercase -- cursor c_ # c_data# All cursors have to start with "c_" ends with "#" in lowercase -- record rec # rec_date# All records have to start with "rec_" ends with "#" in lowercase -- type t_ # t_data# All types have to start with "t_" ends with "#" in lowercase -- exception e_ # e_frod# All exceptions have to start with "e_" ends with "#" in lowercase /** *    (PL/SQL package) * @author Prigozhiy * @version 1 (29.09.2013) * @headcom */ /*    EMS */ v_esbusername varchar2(20) ; /** ,    * @author Prigozhiy * @version 2 (29.05.2013) * @param in_text#    * @param out_text#    */ procedure pr_output_text ( in_text# in varchar2, out_text# out varchar2 ); /** ,    * @author Prigozhiy * @version 1 (21.05.2013) * @param in_text#    * @return    * @deprecated <a href="EXAMPLE.html#FN_OUTPUT_TEXT_V1(VARCHAR2)">FN_OUTPUT_TEXT_V1</a> * @throws PROGRAM_ERROR ORA-06501   PL/SQL * @see #FN_OUTPUT_TEXT_V1(VARCHAR2) */ function fn_output_text ( in_text# in varchar2 ) return varchar2; /** ,    * @author Prigozhiy * @version 1 (21.05.2013) * @param in_text#    * @return    * @see (<a href="http://%20documentation/html/CONTRACT_RATEPLAN_HISTORY.READcms_cmd.html">CONTRACT_RATEPLAN_HISTORY.READ</a>) * @see (<a href="http://jira.main.by/browse/BSCSOA-87">BSCSOA-87</a>) */ function fn_output_text_v1 ( in_text# in varchar2 ) return varchar2; end EXAMPLE; create or replace package body EXAMPLE is /* Revisions: Ver Date Author Description --------- ---------- --------------- ------------------------------------ 1.0 28.05.2013 Prigozhiy Created this procedure 2.0 29.05.2013 Prigozhiy http://jira.main.by/browse/ONEC-49 */ procedure pr_output_text ( in_text# in varchar2, out_text# out varchar2 ) is begin out_text# := upper(in_text#); end; /* Revisions: Ver Date Author Description --------- ---------- --------------- ------------------------------------ 1.0 29.05.2013 Prigozhiy Created this procedure */ function fn_output_text ( in_text# in varchar2 ) return varchar2 is out_text# varchar2(100); begin out_text# := substr(upper(in_text#),1,100); return out_text#; end; function fn_output_text_v1 ( in_text# in varchar2 ) return varchar2 is out_text# varchar2(100); begin out_text# := substr(upper(in_text#),1,100); return out_text#; end; end EXAMPLE;

Pour la fonction et la procédure

Je vous demande de faire attention à la description du document commence immédiatement après la fonction ou la procédure de nom:

 create or replace function get_change_rp_current_month /** ... 

 create or replace function get_change_rp_current_month /**      * @author Prigozhiy * @version 1 (30.05.2013) * @param in_coid id  * @return 0-  , 1-    * @see (<a href="http://documentation/html/CONTRACT_RATEPLAN_HISTORY.READcms_cmd.html">contract.GET_HISTORY_LAST_rateplan_date</a>) * @see (<a href="http://jira.main.by/browse/BSCSOA-87">BSCSOA-87</a>) */ ( in_coid in number ) RETURN number is v_date date; BEGIN /* Revisions: Ver Date Author Description --------- ---------- --------------- ------------------------------------ 1.0 30.05.2013 Prigozhiy Created this procedure */ v_date := contract.GET_HISTORY_LAST_rateplan_date(co_id => in_coid); if TRUNC(sysdate, 'month')> v_date then return 0; else return 1; end if; end;

Si vous utilisez PL / SQL Developer pour vous aider


Formatage dans un seul style

Créez pl_sql_beautifief_rules.br sl. contenu:

 Version=1 RightMargin=80 Indent=2 UseTabCharacter=FALSE TabCharacterSize=2 AlignDeclarationGroups=TRUE AlignAssignmentGroups=TRUE KeywordCase=2 IdentifierCase=2 UseSpecialCase=FALSE ItemList.Format=1 ItemList.Align=TRUE ItemList.CommaAfter=TRUE ItemList.AtLeftMargin=FALSE EmptyLines=1 ThenOnNewLine=FALSE LoopOnNewLine=FALSE DML.LeftAlignKeywords=FALSE DML.LeftAlignItems=FALSE DML.OnOneLineIfPossible=FALSE DML.WhereSplitAndOr=TRUE DML.WhereAndOrAfterExpression=FALSE DML.WhereAndOrUnderWhere=TRUE DML.JoinSplitBeforeOn=TRUE DML.InsertItemList.Format=1 DML.InsertItemList.Align=FALSE DML.InsertItemList.CommaAfter=TRUE DML.InsertItemList.AtLeftMargin=FALSE DML.SelectItemList.Format=2 DML.SelectItemList.Align=TRUE DML.SelectItemList.CommaAfter=TRUE DML.SelectItemList.AtLeftMargin=FALSE DML.UpdateItemList.Format=2 DML.UpdateItemList.Align=TRUE DML.UpdateItemList.CommaAfter=TRUE DML.UpdateItemList.AtLeftMargin=FALSE ParameterDeclarationList.Format=1 ParameterDeclarationList.Align=TRUE ParameterDeclarationList.CommaAfter=TRUE ParameterDeclarationList.AtLeftMargin=TRUE RecordFieldList.Format=1 RecordFieldList.Align=TRUE RecordFieldList.CommaAfter=TRUE RecordFieldList.AtLeftMargin=FALSE SplitAndOr=FALSE AndOrAfterExpression=FALSE [SpecialCase]

Ouvrez ensuite le menu PL / SQL Developer -> Tools - Preferences, puis l'onglet PL / SQL beautifief, puis le fichier de règles et spécifiez le fichier pl_sql_beautifief_rules.br et confirmez les modifications.

Maintenant, nous sélectionnons le code écrit pl / sql et le formatons dans un style en cliquant sur le menu Edition -> Beautifief PL / SQL.

Utiliser des modèles

La fenêtre Modèles (près de la fenêtre Liste), puis le bouton gauche de la souris Nouveau modèle.

 /** [Description] * @author [Username = $OSUSER] * @version [Version=1.0] ([Date = $DATE])[+Depricated=" * @deprecated "][Depricated][+Param 1=" * @param "][Param 1][+Param 2=" * @param "][Param 2][+Param 3=" * @param "][Param 3][+Param 4=" * @param "][Param 4][+Param 5=" * @param "][Param 5][+Return=" * @return "][Return][+See=" * @see "][See] */

Source: https://habr.com/ru/post/fr442980/

More articles:


All Articles