{UT05}
Documentación y Control de Versiones
2022-23
¿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
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
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
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
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
# 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!");
}
}# UT05
Instalación JavaDoc IDE NetBeans
1. Comprobar la versión de JDK instalada en el equipo
# UT05
Instalación JavaDoc IDE NetBeans
2. Descargar el Javadoc para la versión de JDK instalada
# UT05
Instalación JavaDoc IDE NetBeans
3. Abrimos NetBeans para ir a Tools --> Java Platforms
¿Qué vamos a ver hoy?
Iniciación a Git
Principales conceptos
1.
# UT05
Tutorial Git
Haciendo uso de la línea de comandos
DAW-UT05-Documentación y Control de Versiones
By Manuel Jesús Rodríguez Arabi
