16f6c0aecf
Inline adoc files when they are included exactly once. Also fix language tags because this inlining gives us better information on what language the code is written in.
106 lines
1.5 KiB
Plaintext
106 lines
1.5 KiB
Plaintext
== Why is this an issue?
|
|
|
|
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
|
|
|
|
[source,sql]
|
|
----
|
|
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
|
|
|
|
[source,sql]
|
|
----
|
|
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.
|
|
|
|
|
|
[source,sql]
|
|
----
|
|
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)
|
|
|
|
=== Message
|
|
|
|
Add a documenting comment to this [function|procedure] "{XXX}".
|
|
|
|
|
|
endif::env-github,rspecator-view[]
|