Guia para crear documentacion con PhpDocumentor
Por que escribir Buena documentacion al codigo abierto Escribir Buena documentacion es esencial en el exito de cualquier proyecto de software: la calidad de esta documentacion puede ser mas importante que la calidad del codigo en si. phpDocumentor está diseñado para facilitar el proceso de documentación. phpDocumentor incluso hace posible el generar paquetes separados de documentación desde el mismo codigo fuente.
Escribiendo grandiosa documentación considerando la audiencia. La primera pregunta que cualquier escritor debe hacer es ¿Quién es mi público? Esto contestará muchas preguntas. Sólo se piensa que el software es usado para más software, como cualquier producto de MS. Los programadores son las únicas personas que tienen el acceso al código fuente. El desafío en este caso es escribir la documentación muy bien para el usuario final.
Al escribir documentación para un proyecto de fuente abierta se piensa que ambos son usados extendidos, este desafío se magnifica por el hecho de que muchas personas también pensarán en extender el codigo, o incluso el hallazgo de errores y su reparacion. Estos dos públicos cuidan ser opuestos a nosotros en sus necesidades.
Un usuario final generalmente quiere:
- el estilo de las instrucciones escritas, eso explica y describe los conceptos generales más de cómo una variable particular se usa
- La información de la interfaz , ningún detalle de bajo nivel
- Los ejemplos de cómo usar, y guías didácticas
Considerando que un programador además puede querer:
- Los detalles del programa en cómo los elementos actúan recíprocamente, qué elementos usan otros
- Donde en el código fuente una acción o serie de acciones ocurren
- Cómo extender el código para agregar una nueva funcionalidad
Estos dos tipos de usuarios no pueden ser reparados por sólo documentación del API o sólo guías didácticas, pero una mezcla sutil de los dos.
El uso de phpDocumentor para hacer documentación dirigida a los dos públicos, puede necesitar hacer dos juegos separados de documentación! pueden usarse los phpDocumentor para crear esta opción que usa unas cosas. Primero, usando las opciones de archivo-selección de orden-línea, uno puede escribir dos juegos de documentación, uno para los usuarios finales, y el otro para programadores, y los pone en subdirectorios diferentes. Por ejemplo, uno podría poner el docs del enduser en el enduser/tutorials y los documentos del programador en el tutorial de porgramacion además, usando el @ la etiqueta de acceso, uno puede marcar los elementos programador-nivelados con @ el acceso privado, y ellos se ignorarán por defecto.
El @ la etiqueta interior @ interior los inline etiquetan la estructura puede usarse para marcar documentación que es de bajo nivel o interior a un público más pequeño de diseñadores. Al crear la documentación del programador, encienda la opción privada y el detalle de bajo nivel se generará. Más importante, el en-código documenta en su DocBlocks debe escribirse dondequiera que para fin-usuarios y programadores posible. el phpDocumentor usa el rasgo del encadenamiento de guías didáctica para unirse la documentación relacionada juntos como los capítulos en un libro, y ésta es otra manera de organizar la documentación. Experimente, y hallazgo lo que es mejor para las necesidades de su proyecto.
Hay muchas maneras de crear la documentación buena, pero quizás el mejor es leer lo que usted ha escrito de las perspectivas diferentes. Abra su documentación, e intenta usarlo para deducir su proyecto del software. Si esto es difícil, se remonta y revisa o vuelve a escribir. Quite algo que está confundiendo o innecesario, asegúrese todo está allí eso se necesita, y entonces cuando parece bueno, pregúntele a un usuario del php que no conoce su proyecto, o incluso non-programador para leerlo y usar sus reacciones a sastre la documentación.
La conclusión
El uso de phpDocumentor mejorará la mirada definitivamente y se sentirá de su documentación, pero no detiene allí, permítale ayudar que usted crear documentos verdaderamente dinámicos que se mantienen fácilmente y guardaron moderno. ¡Después de todos, los granes docs para los grandes programas ayudarán afianzar el trono justo de PHP allí como el exterior mejor! el phpDocumentor 1.2.2 Guía didáctica aprenda a usar el phpDocumentor para documentar
La introducción
el phpDocumentor es el sistema de la documentación automático más avanzado escrito para PHP, en PHP. Este paquete tiene muchos rasgos:
- El Nuevo nuevo parser tokenizer-basado Excitando es literalmente dos veces tan rápido como el parser anterior!
- Nuevo @ la etiqueta de la categoría, útil para los peardoc2 y otros usos.
El Nuevo nuevo Conversor de CSV:dia2code genera rendimiento que puede usarse para crear un diagrama de UML, y genera el código del diagrama que usa Harald el Fielkers dia2code proyecto
- Nuevo versátil @ interior, inline {@ interior}}, @ las etiquetas del ejemplo
- La Nueva Marca el nuevo manual del phpDocumentor extenso
- La Nueva documentación del extended/tutorial en el docbook estructura con unirse a cualquier elemento y a otra documentación, incluso los subalterno-sección, del código de la fuente (vea las Guías didáctica del phpDocumentor)
- Las Nuevas plantillas del docblock para consumir menos la repetición
- Nuevo {@ la fuente} los inline etiquetan para desplegar la fuente de la función
Las Nuevas plantillas de XML:DocBook:peardoc2 para diseñadores de la PERA
- La Nueva facilidad Mayor de extender a un Conversor, vea el Manual del Conversor
- Se mueven las Nuevas Opciones del código de la fuente a phpDocumentor.ini, vea phpDocumentor.ini - las opciones de la configuración globales
- la habilidad de analizar cualquier PHP archiva, sin tener en cuenta el formato de la documentación
- conforma flojamente al protocolo de JavaDOC, y estará familiarizado a programadores de Java
- documenta todos incluyen, constantes, funciones, las funciones estáticas, las clases, los métodos, las variables estáticas, las variables de la clase, y puede documentar variables globales y las guías didáctica externas
- automóvil-uniéndose a las funciones de PHP pre-definidas
El rendimiento en HTML, CHM, PDF, XML los formatos de DocBook
- los templateable con muchos ataron las plantillas
- la vinculación automática a los elementos en cualquiera documentó el paquete
- los conflictos de nombre de documentos entre los paquetes para ayudar evitan los errores de PHP
- la documentación CVS directamente.
el apoyo para JavaDoc doclet-como el rendimiento a través de los Conversores
- error/warning que rastrea el sistema
- inteligencia de la clase extrema: hereda documentación, el paquete,
phpdoc.de DocBlock completos etiquetan el apoyo. Las sumas incluyen @ el var, @ la magia, @ el deprec, @ el todo, y phpdoc.de que analiza de @ el param.
- el posicionamiento alfabético de todos los elementos por el paquete y en conjunto
- los árboles de la clase
- MUCHO más de sólo esta lista corta
los Elementos esenciales del phpDocumentor Empezando desde el principio El proceso de la documentación empieza con el elemento más básico de phpDocumentor: un bloque de la Documentación o DocBlock. Un DocBlock básico se parece a:
<1 /**> 2 * <3 */>
Un bloque de C++-estilo extendido comentario de PHP con que empieza / * * y tiene un * al principio de cada línea. DocBlocks preceden el elemento que ellos están documentando.
DocBlocks
Un DocBlock contiene tres segmentos básicos en este orden:
- La Descripción corta
- La Descripción larga
- Las etiquetas
Las salidas de la Descripción Cortas en la primera línea, y puede terminarse con una línea pálida o un período. Un período dentro de una palabra (como example.com o 0.1%) se ignora. Si la Descripción Corta se volviera mucho tiempo más de tres líneas, sólo la primera línea se toma. La Descripción Larga continúa para las tantas líneas como deseado y puede contener el encarecimiento del html para el formato del despliegue. Aquí es una muestra DocBlock con un Calzón y una Descripción Larga:
# /** # * return the date of Easter > # * # * Using the formula from "Formulas that are way too complicated for anyone to # * ever understand except for me" by Irwin Nerdy, this function calculates the # * date of Easter given a date in the Ancient Mayan Calendar, if you can also # * guess the birthday of the author.> # */
Los DocBlock Descripción detalles
A partir de phpDocumentor 1.2.0, la descripción larga y corta de un DocBlock se analiza para unas etiquetas del html selectas que determinan el formato adicional. Debido a la naturaleza del rendimiento de phpDocumentor como el múltiple-formato, el html recto no se permite en un DocBlock, y se convertirá en el texto llano por todos los conversores a menos que es uno de estas etiquetas:
b--el texto del emphasize/bold>
- el código--Use esto para rodear el php codifique, algunos conversores lo resaltarán
- el br--el descanso de la línea duro, puede ignorarse por algunos conversores
- i--el italicize/mark como importante
- el kbd--denote el despliegue de input/screen de teclado
- el li--el artículo de la lista
- el ol--pidió la lista
- p--Si adjuntaba todos los párrafos, por otra parte será considerado el texto
- por--los descansos de línea de Confitura y espaciando, y asume todas las etiquetas son el texto (como el CDATA de XML)
- el samp--denote muestra o ejemplos (el non-php)
- el ul--la lista del unordered
el var--denote un nombre inconstante>
Comentarios
Hay que redactar un poco mejor el documento, no se si ha sido traducido y le falta contextualizar mas! -- JorgeCortes 2006-08-07 18:04:58