98 lines
1.4 KiB
Plaintext
98 lines
1.4 KiB
Plaintext
Each function and procedure should be documented with a comment either just before or right after the ``++IS++`` or ``++AS++`` keyword it to explain its goal and how it works.
|
|
|
|
|
|
== Noncompliant Code Example
|
|
|
|
----
|
|
CREATE FUNCTION my_function RETURN PLS_INTEGER AS
|
|
BEGIN
|
|
RETURN 42;
|
|
END;
|
|
/
|
|
|
|
CREATE PACKAGE my_package AS
|
|
|
|
PROCEDURE my_procedure;
|
|
|
|
FUNCTION my_function RETURN PLS_INTEGER;
|
|
|
|
END my_package;
|
|
/
|
|
----
|
|
|
|
|
|
== Compliant Solution
|
|
|
|
----
|
|
CREATE FUNCTION my_function RETURN PLS_INTEGER AS
|
|
-- Computes the meaning of life
|
|
BEGIN
|
|
RETURN 42;
|
|
END;
|
|
/
|
|
|
|
CREATE PACKAGE my_package AS
|
|
|
|
-- This is documentation
|
|
PROCEDURE my_procedure;
|
|
|
|
/*
|
|
This is documentation
|
|
*/
|
|
FUNCTION my_function RETURN PLS_INTEGER;
|
|
|
|
END my_package;
|
|
/
|
|
----
|
|
|
|
|
|
== Exceptions
|
|
|
|
Functions are procedures declared in package bodies, and anonymous PL/SQL blocks do not have to be documented.
|
|
|
|
|
|
----
|
|
DECLARE
|
|
PROCEDURE helper_procedure AS
|
|
BEGIN
|
|
NULL;
|
|
END;
|
|
BEGIN
|
|
helper_procedure;
|
|
END;
|
|
/
|
|
|
|
CREATE PACKAGE my_package AS
|
|
|
|
-- This is documentation
|
|
PROCEDURE public_procedure;
|
|
|
|
END my_package;
|
|
/
|
|
|
|
CREATE PACKAGE BODY my_package AS
|
|
|
|
PROCEDURE helper_procedure AS
|
|
BEGIN
|
|
NULL;
|
|
END;
|
|
|
|
PROCEDURE public_procedure AS
|
|
BEGIN
|
|
helper_procedure;
|
|
END;
|
|
|
|
END my_package;
|
|
/
|
|
----
|
|
|
|
ifdef::env-github,rspecator-view[]
|
|
|
|
'''
|
|
== Implementation Specification
|
|
(visible only on this page)
|
|
|
|
include::message.adoc[]
|
|
|
|
endif::env-github,rspecator-view[]
|