rspec/rules/S1638/plsql/rule.adoc

== 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[]