› ›

Sistema de documentación de archivos kumbia

proclamoproclamo
edited mayo 2008 in Documentación
Además del esfuerzo de escribir un buen manual para la versión 0.5, debemos hacer un buen esfuerzo también en la documentación del código. He intentado generar una ayuda con phpDocumentor, para tener una referencia de la api a modo del javadoc, y la verdad es que se generan muy pocas páginas. Las clases que encuentra son las de las librerías externas (excel,phpmailer, el tema de las chart, etc).
Veo que el código está bastante bien documentado, pero supongo que para otro programa generador de documentación ¿cuál es?

Creo que es muy importante que nos pongamos de acuerdo con qué programa vamos a generar la documentación de las clases y documentar el código de acuerdo a ese programa.

El tener una referencia rápida de la api es indispensable, y más en esta versión, donde el número de clases ha aumentado bastante.

Comentarios

  • phillipophillipo
    edited 7:30
    Estoy muy de acuerdo, lo unico de lo que tengo dudas, respecto al software de generación de documentación, es si previamente los archivos que contienen los datos deben tener algun tipo de comentario o sistema para generar una buena documentación.

    Pero si, deberiamos hacer algo al respecto para complementar la documentacion.
  • proclamoproclamo
    edited 7:30
    Si, tienen que tener un formato preestablecido los comentarios.
    Fíjate en el código, antes de cada función encontramos:
    /**
 * Esta es la clase principal del framework, contiene metodos importantes
 * para cargar los controladores y ejecutar las acciones en estos ademas
 * de otras funciones importantes
 *
 * @category Kumbia
 * @package Kumbia
 * @abstract
 * @copyright Copyright (c) 2005-2007 Andres Felipe Gutierrez (andresfelipe at vagoogle.net)
 * @copyright Copyright (c) 2008-2008 Emilio Rafael Silveira Tovar (emilio.rst at gmail.com)
 * @license http://www.kumbia.org/license.txt GNU/GPL
 */
abstract class Kumbia extends Object {

	/**
	 * Almacena la configuracion global del framework
	 *
	 * @var Config
	 */
	public $config;
             ............

    Que le indica al programa qué nombre tiene la clase. @param para decirle quétipo de parámetros recibe, @return para indicar qué devuelve, y muchas cosillas más por el estilo.

    Los comentarios del código de Kumbia están formateados, pero no para phpDocumentor, porque ya lo intenté y me salieron muchos errores y avisos.

    Si alguien pudiera decirnos con qué programa se podría generar...
  • proclamoproclamo
    edited 7:30
    Bueno, ya he descubierto cómo crear los archivos de documentación.

    Kumbia utiliza phpDocumentor, lo que pasa que el que está integrado con el Zend Studio. Lo he instalado, lo he probado y voilà, ha funcionado.
Sign In or Register to comment.