Внутри команды нужно разработать свои стандарты и правила, а оформление документации — это одно из главных правил работы в команде.
Ну, поехали…
Ссылка на сам инструмент pldoc.
По ссылки хорошо все расписано как работать и формировать документацию, но чтобы было проще приведу примеры и скрипты.
Устанавливаем(распаковываем архив) и создаем в корне run.bat
где:
Запускаем и получаем готовую документацию, по правилам оформления pl/sql кода описанному ниже.
Правила оформления.
Правила оформления.
Прошу обратить внимания описание док-ции начинается сразу же после названия function or procedure:
Создаем pl_sql_beautifief_rules.br сл. содержания:
Затем открываем PL/SQL Developer -> меню Tools — Preferences, за тем вкладка PL/SQL beautifief далее rules file и указываем файл pl_sql_beautifief_rules.br и подтверждаем изменения.
Теперь выделяем написанный код pl/sql и форматируем одним стилем нажав на меню Edit — > PL/SQL beautifief.
Окно Templates(рядом рабочее окно Window List ) далее левая кнопка мыши New Template.
Ну, поехали…
Ссылка на сам инструмент pldoc.
По ссылки хорошо все расписано как работать и формировать документацию, но чтобы было проще приведу примеры и скрипты.
Устанавливаем(распаковываем архив) и создаем в корне run.bat
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
где:
- -d '%TOMCAT_HOME%/Tomcat 7.0/webapps/plsqldoc' — папка куда будет формировать документация;
- -url
jdbc:oracle:thin:@host:port:SID
сервер базы данных откуда браться данные; - -sql API.%%%%T%%%%,SALE.A%%%%,BILLING_API.%%%%
API.%%%%T%%%% — брать все объекты схемы API содержащие букву Т;
SALE.A%%%% — брать все объекты схемы SALE начинающиеся на букву Т;
BILLING_API.%%%% — брать все объекты схемы BILLING_API;
Запускаем и получаем готовую документацию, по правилам оформления pl/sql кода описанному ниже.
Пример оформления
Правила оформления.
Правила оформления.
Для 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;
Для function и procedure
Прошу обратить внимания описание док-ции начинается сразу же после названия function or procedure:
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;
Если вы пользуетесь PL/SQL Developer в помощь
Форматируем одним стилем
Создаем pl_sql_beautifief_rules.br сл. содержания:
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]
Затем открываем PL/SQL Developer -> меню Tools — Preferences, за тем вкладка PL/SQL beautifief далее rules file и указываем файл pl_sql_beautifief_rules.br и подтверждаем изменения.
Теперь выделяем написанный код pl/sql и форматируем одним стилем нажав на меню Edit — > PL/SQL beautifief.
Используйте Templates
Окно Templates(рядом рабочее окно Window List ) далее левая кнопка мыши New Template.
/** [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]
*/