Área de Tecnologías de la Información y las Comunicaciones Aplicadas
Área de Tecnologías de la Información y las Comunicaciones Aplicadas Universidad de Murcia
Área de Tecnologías de la Información y las Comunicaciones Aplicadas
ATICA
25.09.2017
 
 
Cómo documentar el código PL/SQL Imprimir E-mail
Esta Normativa fue publicada por MNCS el 13-3-2009, y es de obligado cumplimiento para TODOS los nuevos proyectos de ATICA, a partir de dicha fecha.

Documentación del código PL/SQL

El objetivo fundamental es que cualquier desarrollador que vaya a utilizar un procedure/function/package que no es suyo, pueda acceder fácilmente a la documentación de la interfaz del objeto en cuestión. Por lo tanto, en este documento vamos a centrarnos sobre todo en como documentar la interfaz del objeto que puede ser utilizado por otros compañeros.

Para documentar código PL/SQL, tanto en procesos de base de datos como en formularios, seguiremos la siguiente normativa (basada en PLDOC, que a su vez está basada en javadoc):

  • Las marcas para documentar empiezan por /** y terminan por */ (fíjate que hay dos asteriscos en la marca de inicio). Para documentar un procedure/function interno al procedure/function/package que estoy documentando, marcaré los comentarios con /* y */ (un solo asterisco en la marca de inicio).
  • La primera línea, justo después de /** (y hasta el primer punto), incluirá una descripción breve. Después se indicará la descripción detallada.
  • La documentación general sobre un paquete se indica justo antes de la función PAQUETE_INFO, que debe contener cualquier paquete. Esta función, además puede devolver un VARCHAR2 con la documentación general del paquete.
  • La documentación de funciones/procedimientos de un paquete se escribe antes del objeto a documentar, es decir, en la línea anterior a la que contiene la palabra clave FUNCTION o PROCEDURE.
  • Para funciones/procedimientos aislados, la documentación se escribe justo antes del BEGIN (en la línea justo anterior), y además, para que la documentación se vea se deben poner dos guiones justo después de BEGIN (en la misma línea), de modo que se vea “BEGIN –”.
  • Las variables de un procedimiento o una función se documentan en la misma línea.
  • La documentación admite HTML, por lo que los saltos de línea, los espacios, etc. no se tienen en cuenta, deben ser introducidos mediante código XHTML (por ejemplo, un salto de línea sería <br />).
  • Los parámetros se documentan en el mismo orden en que se definen en el procedimiento/función.
  • Los tags permitidos (y el orden en que se deben indicar) son:
    • @param Documenta un parámetro (una línea @param para cada parámetro indicando el nombre en mayúsculas del parámetro, de modo que se indiquen en orden, y sin poner saltos de línea en el comentario de un mismo parámetro)
    • @exception Para documentar las EXCEPTION que se capturen (una línea @exception por cada excepción, indicando el nombre en mayúsculas de la excepción)
    • @return Para indicar qué devuelve, en caso de ser una función
    • @deprecated Sólo en el caso de que ya esté anticuado (indicaremos "true")
    • @see Si está "deprecated" (obsoleto), aquí indicaremos el objeto nuevo que se debe usar en su lugar
    • @author Nombre del usuario de correo quien lo hizo
    • @version Versión actual, indicando código de versión, fecha y autor de los cambios  (sólo admite un tag @version, de modo que si se quieren indicar varias versiones, hay que hacerlo en la misma línea, indicando los saltos de línea con <BR />)
    • @since Desde qué versión existe el objeto (este tag es opcional, pues sólo tiene sentido cuando a partir de una determinada versión introducimos un procedimiento/función nuevo en el paquete)

Más abajo se puede ver cómo se usan, en los ejemplos.

jOra es un plugin para Eclipse para desarrollo pl/sql que permite ver la documentación PLDOC de un paquete, simplemente situando el puntero del ratón sobre el nombre del paquete.

Ejemplo de función aislada

En el caso de una función aislada, como se puede observar, primero incluimos una descripción breve (terminada en un punto ”.” más el salto de línea ”<br />”), después la explicación detallada, y los tags a incluir son: @param (tantos como parámetros haya, y en el orden correcto), @exception (si es que la función maneja excepciones pl/sql), @return, @author (nombre del usuario de correo del autor) y @version.

¡¡¡ Ojo !!! al ser una función aislada (o un procedimiento) hay que poner un doble guión "--" después del "BEGIN" (justo en la misma línea), y los comentarios con la documentación irán justo antes de la línea "BEGIN --". Además, el comentario que documenta a cualquier function/procedure interno debe empezar por un solo asterisco.

CREATE OR REPLACE
FUNCTION FUNCION(
  PARAMETRO1          TIPO1,
  PARAMETRO_MAS_LARGO TIPO_MAS_LARGO,
  PARAMETRO2          TIPO2           DEFAULT NULL,
  PA                  TIPO3
  ) RETURN ALGO IS
 
 
  VC_VARIABLE     VARCHAR2(X);             /**Comentario sobre la varibale*/
  N_VARIABLE      NUMBER(X);               /**Comentario sobre la varibale*/
  D_VARIABLE      DATE         := SYSDATE; /**Comentario sobre la varibale*/
  B_OTRA_VARIABLE BOOLEAN      := TRUE;    /**Comentario sobre la varibale*/

  /*
  * Docuentación interna de la sub-función F_BORRAME (fíjale que la línea superior a ésta no lleva doble asterisco
  * @return  Nulo, pues esta función es sólo un prototipo.
  * @author  juanlu
  * @version 1.0 juanlu 29/04/2009
  */
  FUNCTION F_BORRAME RETURN VARCHAR2 IS
  BEGIN
    RETURN NULL;
  END;
 

/**
 *   breve de la funcionalidad del objeto aislado a documentar. <br />
 * Explicación detallada del objeto.
 * @param PARAMETRO1          Comentario sobre el parámetro.
 * @param PARAMETRO_MAS_LARGO Comentario sobre el parámetro.
 * @param PARAMETRO2          Comentario sobre el parámetro.
 * @param PA                  Comentario sobre el parámetro.
 * @exception NO_DATA_FOUND Se ejecuta la acción ACCION.
 * @exception OTHERS        Se devuelve el valor de error.
 * @return Nulo, pues esta función es sólo un prototipo.
 * @author  fjcosta
 * @version 1.0 fjcosta 20/02/2009<BR/> 1.1 juanlu 25/02/2009
 */
BEGIN --
 
  SENTENCIA1;
 
  --Comentario técnico sobre la sentencia2
  /**Comentario para la documentación, sobre el siguiente bloque de código.*/
  SENTENCIA2;
  IF ALGO THEN
    --Comentario técnico sobre la sentencia 3.
    SENTENCIA3;
  END IF;
 
  RETURN NULL;
 
EXCEPTION
  WHEN NO_DATA_FOUND THEN
    ACCION;
  WHEN OTHERS THEN
    RETURN SQLCODE;
END;

Ejemplo de paquete

En el caso del paquete, en primer lugar incluimos una función llamada PAQUETE_INFO cuya documentación se refiere al paquete completo (con su descripción breve terminada en ”.” más ”<br />”, la detallada, @author y @version).

Después vamos documentando cada uno de los procedimientos y funciones que componen la interfaz del paquete (con su descripción breve terminada en ”.” más <br />, la detallada, @param para cada uno de los parámetros y en orden, @return si es función, @author, @version con las versiones separadas por ”<br />”, y @since indicando desde qué versión existe dicho procedimiento/función).

CREATE OR REPLACE
PACKAGE PQ_DOCPLSQL AS
 
  TYPE VC_ARR IS TABLE OF VARCHAR2(32767) INDEX BY BINARY_INTEGER;
 
  /**                                                                           
  * Descripción breve.
  * Información detallada.
  * @author  juanlu
  * @version 1.0 juanlu 20/2/2009<br /> 1.1 juanlu 25/2/2009
  */
  FUNCTION PAQUETE_INFO RETURN VARCHAR2;
 
  /**                                                                           
  * Dado un determinado objeto pl/sql almacenado en BD, genera el HTML con la documentación.<br />
  * Para mostrar la documentación de un objeto, busca en el código las palabras clave "procedure" o
  * "function", y muestra la documentación que hay justo antes de dicha palabra clave.
  * @param P_NOMBRE  Nombre del objeto PL/SQL
  * @param P_TIPO    Tipo del objeto PL/SQL: PACKAGE, PROCEDURE, FUNCTION, TRIGGER
  * @param P_USUARIO Usuario de la BD propietario del objeto
  * @return          No tiene parámetro de salida
  * @author  juanlu
  * @version 1.0 juanlu 20/02/2009
  * @since   1.0
  */
  PROCEDURE DOCAHTML(
    P_NOMBRE  IN VARCHAR2 DEFAULT NULL,
    P_TIPO    IN VARCHAR2 DEFAULT NULL,
    P_USUARIO IN VARCHAR2 DEFAULT NULL
    );
 
  /**                                                                           
  * Permite elegir un usuario y un paquete concretos. <br />
  * Encadena tres formularios que van pidiendo el esquema, tipo de objeto y objeto en cuestión.
  * @param P_NOMBRE  Nombre del objeto PL/SQL
  * @param P_TIPO    Tipo del objeto PL/SQL: PACKAGE, PROCEDURE, FUNCTION, TRIGGER
  * @param P_USUARIO Nombre del usuario de BD
  * @exception       NO_HAY_DATOS si la lista de usuarios (o de objetos) está vacía
  * @return          No tiene parámetro de salida
  * @author  juanlu
  * @version 1.0 juanlu 25/02/2009
  * @since   1.1
  */
  PROCEDURE ELIGE_USUARIO(
    P_NOMBRE  IN VARCHAR2 DEFAULT NULL,
    P_TIPO    IN VARCHAR2 DEFAULT NULL,
    P_USUARIO IN VARCHAR2 DEFAULT NULL
    );
 
END PQ_DOCPLSQL;


Autor: Juan Luis Serradilla
Fecha: 13-3-2009
Última modificación ( 20.09.2011 )
 
Área de Tecnologías de la Información y las Comunicaciones Aplicadas
Volver al incio del documento Volver al inicio del documento
Área de Tecnologías de la Información y las Comunicaciones Aplicadas