{UT05}

Documentación y Control de Versiones

2022-23

Manuel Jesús Rodríguez Arabi

¿Qué vamos a ver hoy?

Documentación de aplicaciones web

¿Qué conviene documentar en una aplicación?

1.

2.

PhpDocumentor

Generar documentación para proyectos en PHP

3.

JavaDoc

Generar documentación automática a partir de código fuente Java.

# UT05

# UT05

Documentación de Aplicaciones Web

Se debe documentar 3 aspectos fundamentales

Interfaz

Implementación

Toma de decisiones

¿Qué hace? (funciones, métodos, parámetros)

Explicación paso a paso, uso de variables, algoritmos, etc

Por qué se ha implementado así y no de otra manera

La información de la interfaz conviene pasarla a un documento independiente del código fuente (manual de uso)

HERRAMIENTAS

Existen algunas herramientas que permiten generar documentación de forma automática a partir del código fuente.

PhpDocumentor

JavaDoc

# UT05

PhpDocumentor

permite generar automáticamente una buena documentación de nuestro código haciendo uso de comentarios y etiquetas especiales

Desde línea de comandos

Interfaz Web (incluida)

Desde código (scripts propios)

# UT05

PhpDocumentor

En cualquier caso siempre habrá que especificar estos parámetros

Directorio del proyecto (raíz)
los @package (opcional)
Directorio de generación de la documentación
Pública (sólo interfaz) o interna (@internal)
Formato de salida de la Documentación (html, PDF, XML)

# UT05

PhpDocumentor

La documentación se distribuye en "DocBlocks" que van antes del elemento a documentar

<?php  

    /**
     * suma
     *
     * @param  mixed $a
     * @param  mixed $b
     * @return void
     */
    function suma($a, $b){
        return $a + $b;
    }

?>

# UT05

PhpDocumentor

Elementos que pueden ser documentados

define / function / class / class vars
include / require / include_once / require_once
global variables

@access : Para generar documentación solo de la interfaz y no de la implementación

@author: Autor de ese fragmento de código

@copyright: Información sobre derechos

@ignore: No se documenta por phpDocumentor

@deprecated: Para indicar que no se use, no disponible en futuras versiones

# UT05

PhpDocumentor

Un ejemplo sobre marcas internas en DockBlock podría ser:

<?php  
    /**
     * suma
     * @author Manu
     * @copyright Creative Commons 4.0
     * @param  mixed $a
     * @param  mixed $b
     * @return void
     */
    function suma($a, $b){
        return $a + $b;
    }

?>

Instalación

Proceso de Instalación de phpDocumentor

Ver tutorial

# UT05

JavaDoc

es una utilidad para generar APIs (Aplication Programing Interface) en formato HTML de un archivo de código fuente Java

Etiquetas de bloque

@etiqueta

Etiquetas inline

{@tag}

# UT05

JavaDoc

Previamente a la instalación de Javadoc, tendremos en cuenta que estamos realizando la programación Java desde una herramienta IDE como puede ser Eclipse o NetBeans, aunque ya se puede integrar muy fácilmente con otros IDE como VSCode.

# UT05

JavaDoc

Los comentarios JavaDoc están destinados a describir, principalmente, clases y métodos. Recomendable hacer uso de un formato común para que resulten legibles para otros programadores.

/**
      * Una clase para empezar a programar en Java
      * el típico ejemplo de HolaMundo
      * @version 1.0, 21/03/2022
      * @author Manu - Dpto. Desarrollo 
      */
public class holamundo {
   /** 
   * Muestra el mensaje de Hola Mundo
   */
     public static void main(String[] args) {
          // TODO Auto-generated method stub
          System.out.println("Hola mundo!");
     }
}