Diferencias

Muestra las diferencias entre dos versiones de la página.

Enlace a la vista de comparación

Ambos lados, revisión anterior Revisión previa
Próxima revisión
Revisión previa
guidelines:coding_documentation_es [2021/04/26 08:16]
0.0.0.0 creado
guidelines:coding_documentation_es [2021/06/09 10:52] (actual)
Línea 1: Línea 1:
 ====== Guidelines:Coding_Documentation_es ====== ====== Guidelines:Coding_Documentation_es ======
 +{{indexmenu_n>11}}
  
-{{tip|Lea también las [[Guidelines:Coding_Documentation_es|normas de estilo de programación]]}}+<WRAP center round tip 60%> 
 +Lea también las [[Guidelines:Coding_Documentation_es|normas de estilo de programación]] 
 +</WRAP>
  
 Para la documentación del código, nos valemos de la herramienta [[http://www.stack.nl/~dimitri/doxygen/index.html|Doxygen]], por ser multilenguaje, multiplataforma y bastante común entre proyectos de Software libre. Para la documentación del código, nos valemos de la herramienta [[http://www.stack.nl/~dimitri/doxygen/index.html|Doxygen]], por ser multilenguaje, multiplataforma y bastante común entre proyectos de Software libre.
Línea 7: Línea 10:
 La mejor manera de comenzar es leyendo el [[http://www.stack.nl/~dimitri/doxygen/starting.html|manual de Doxygen]] de la página web, en concreto la sección de [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|documentación del código]] es la más útil, pudiendo obviar el resto. Sin embargo, debido a la flexibilidad de Doxygen, aquí se resume el estilo que deben de seguir para que los comentarios del código y la documentación generada sea consistente. La mejor manera de comenzar es leyendo el [[http://www.stack.nl/~dimitri/doxygen/starting.html|manual de Doxygen]] de la página web, en concreto la sección de [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|documentación del código]] es la más útil, pudiendo obviar el resto. Sin embargo, debido a la flexibilidad de Doxygen, aquí se resume el estilo que deben de seguir para que los comentarios del código y la documentación generada sea consistente.
  
-====== Documentación básica ====== +===== Documentación básica ===== 
-{{warning|Asegúrese de haber leido antes la documentación de Doxygen.}}+<WRAP center round important 60%> 
 +Asegúrese de haber leido antes la documentación de Doxygen. 
 +</WRAP>
  
-  * **La documentación debe situarse en los ficheros de código, no de cabecera**. +  * **La documentación debe situarse en los ficheros de código, no de cabecera**.\\ La documentación debe de añadirse siempre que sea posible en los ficheros de código, no en los de cabecera. De este modo se mantienen las cabeceras limpias y pequeñas. //Excepciones a esta norma// son los espacioes de nombre, las clases y los miembros de las clases públicos y privados, que pueden documentarse en la cabecera.
-::La documentación debe de añadirse siempre que sea posible en los ficheros de código, no en los de cabecera. De este modo se mantienen las cabeceras limpias y pequeñas. //Excepciones a esta norma// son los espacioes de nombre, las clases y los miembros de las clases públicos y privados, que pueden documentarse en la cabecera.+
  
-  * **Se usa el estilo de código de C++** +  * **Se usa el estilo de código de C++**\\ La documentación debe hacerse con comentarios con el estilo de C, esto es, entre ''/*'' ''*/''. Los comentarios de C++ de una sola linea con el símbolo ''<nowiki>//</nowiki>'', aunque válidos, no son correctos para hacer nuestra documentación.
-::La documentación debe hacerse con comentarios con el estilo de C, esto es, entre <code>/*</code> <code>*/</code>. Los comentarios de C++ de una sola linea con el símbolo <code><nowiki>//</nowiki></code>, aunque válidos, no son correctos para hacer nuestra documentación.+
  
-  * **Uso del estilo de Javadoc** +  * **Uso del estilo de Javadoc**\\ Para una sintaxis más clara, el estilo es el mismo que Javadoc, así que si se está familiarizado con este sistema de documentación, el uso de Doxygen será más sencillo. **Tenga en cuenta al leer la documentación de Doxygen que dado que se usa el formato de Javadoc, las órdenes comienzan con ''@'' y no con ''\''**. 
-::Para una sintaxis más clara, el estilo es el mismo que Javadoc, así que si se está familiarizado con este sistema de documentación, el uso de Doxygen será más sencillo. **Tenga en cuenta al leer la documentación de Doxygen que dado que se usa el formato de Javadoc, las órdenes comienzan con <code>@</code> y no con <code>\</code>**. +
  
-===== Normas comunes =====+==== Normas comunes ====
 Para cualquiera de los bloques de documentación se usan la siguientes normas. Para cualquiera de los bloques de documentación se usan la siguientes normas.
  
-  * Comienza un bloque de código con <code>/**</code> y un salto de linea. +  * Comienza un bloque de código con ''<nowiki>/**</nowiki>'' y un salto de linea. 
-  * Comienza cada bloque del código con un <code>*</code>. Estos símbolos deben de alinearse al primera <code>*</code> del comienzo del comentario.+  * Comienza cada bloque del código con un ''*''. Estos símbolos deben de alinearse al primera ''*'' del comienzo del comentario.
   * La segunda linea del comentario debe ser una descripción breve del termino a documentar. **Debe de terminar en un punto para que la descripción sea procesada correctamente**.   * La segunda linea del comentario debe ser una descripción breve del termino a documentar. **Debe de terminar en un punto para que la descripción sea procesada correctamente**.
   * Termina la descripción breve con una linea en blanco.   * Termina la descripción breve con una linea en blanco.
Línea 31: Línea 33:
 Ejemplo: Ejemplo:
  
- /** +<code> 
-  * A variable. Just it. +/** 
-  + * A variable. Just it. 
-  * A more elaborate description of the variable. It may + * 
-  * contains a large amount of lines, so please don'+ * A more elaborate description of the variable. It may 
-  * put the description in a single line. + * contains a large amount of lines, so please don'
-  */ + * put the description in a single line. 
- int var;+ */ 
 +int var; 
 +</code>
  
-===== Funciones=====+==== Funciones ====
 Para comentar una función, hay que tener en cuenta, además: Para comentar una función, hay que tener en cuenta, además:
  
-  * Justo después de la descripción breve (o la detallada si se ha incluido) hay que describir los parámetros. Doxygen utiliza la marca <code>@param</code>, seguida del nombre del parámetro y la descripción del mismo.+  * Justo después de la descripción breve (o la detallada si se ha incluido) hay que describir los parámetros. Doxygen utiliza la marca ''@param'', seguida del nombre del parámetro y la descripción del mismo.
   * Después del último comentario una linea en blanco.   * Después del último comentario una linea en blanco.
-  * Por último, con la marca <code>@return</code> se describe el valor devuelto.+  * Por último, con la marca ''@return'' se describe el valor devuelto.
   * Cualquier otro comando de Doxygen irá después de este último, añadiendo justo antes una linea de comentario en blanco.   * Cualquier otro comando de Doxygen irá después de este último, añadiendo justo antes una linea de comentario en blanco.
 Ejemplo: Ejemplo:
  
- /** +<code> 
-  * A normal member taking two arguments and returning an integer value. +/** 
-  + * A normal member taking two arguments and returning an integer value. 
-  * This is an incredible function that will make people happier and stop + * 
-  * wars in the world. + * This is an incredible function that will make people happier and stop 
-  + * wars in the world. 
-  * @param a an integer argument. + * 
-  * @param s a constant character pointer. + * @param a an integer argument. 
-  + * @param s a constant character pointer. 
-  * @return The test results. + * 
-  + * @return The test results. 
-  * @exception MyException throwed if any error happens. + * 
-  * @see otraFuncion + * @exception MyException throwed if any error happens. 
-  */ + * @see otraFuncion 
- int + */ 
- testMe (int a, const char *s) { +int 
-    .... +testMe (int a, const char *s) { 
- }+   .... 
 +} 
 +</code>
  
-===== Clases =====+==== Clases ====
 Las clases en los lenguajes de programación orientados a objetos, deben de documentarse en su declaración, es decir, en los ficheros de cabecera. Los atributos y funciones **privados no deben documentarse**, los **públicos y protegidos** sí, y debe de hacerse **en el fichero fuente**. Ejemplo: Las clases en los lenguajes de programación orientados a objetos, deben de documentarse en su declaración, es decir, en los ficheros de cabecera. Los atributos y funciones **privados no deben documentarse**, los **públicos y protegidos** sí, y debe de hacerse **en el fichero fuente**. Ejemplo:
  
- /** +<code> 
-  * This is a class to manage something. +/** 
-  + * This is a class to manage something. 
-  * Many things can be done with an object of this class. + * 
-  */ + * Many things can be done with an object of this class. 
- class MiClase { + */ 
- private: +class MiClase { 
-        int atr; +private: 
-        int f (); +       int atr; 
- protected: +       int f (); 
-        int bbb; +protected: 
-        int g (); +       int bbb; 
- public: +       int g (); 
-        char *id; +public: 
-        char *getId (); +       char *id; 
- };+       char *getId (); 
 +}; 
 +</code>
  
-===== Tipos estructurados =====+==== Tipos estructurados ====
 La declaración de una estructura o un enumerado, deben de documentarse de la siguiente manera. La declaración de una estructura o un enumerado, deben de documentarse de la siguiente manera.
  
   * Al principio de la definición se añadirá la documentación sobre el tipo.   * Al principio de la definición se añadirá la documentación sobre el tipo.
   * Cada campo o valor se documentará únicamente con un comentario breve, a menos que sea absolutamente necesario.   * Cada campo o valor se documentará únicamente con un comentario breve, a menos que sea absolutamente necesario.
-  * Para que la declaración sea más legible y que los comentarios no estorben para ello, se documentará con el formato de Doxygen para los elementos anteriores al comentario. Es decir, el comentario se pondrá en la misma linea que la definición del campo, con el formato <code>/**<</code> y <code>*/</code>.+  * Para que la declaración sea más legible y que los comentarios no estorben para ello, se documentará con el formato de Doxygen para los elementos anteriores al comentario. Es decir, el comentario se pondrá en la misma linea que la definición del campo, con el formato ''<nowiki>/**<</nowiki>'' ''<nowiki>*/</nowiki>''.
  
 Ejemplo: Ejemplo:
  
- /** +<code> 
-  * A struct that represents a car. +/** 
-  + * A struct that represents a car. 
-  * The structs can have a long description. The fields should not.  + * 
-  */ + * The structs can have a long description. The fields should not.  
- struct MyStruct { + */ 
-      int wheels; /**< Number of wheels. */ +struct MyStruct { 
-      char *id;   /**< Car ID. */ +     int wheels; /**< Number of wheels. */ 
-      int cv;     /**< Motor power in CV. */ +     char *id;   /**< Car ID. */ 
- }+     int cv;     /**< Motor power in CV. */ 
 +} 
 +</code>
  
 Ejemplo de enumerados: Ejemplo de enumerados:
  
- /** +<code> 
-  * Numbers enumerator. +/** 
-  */ + * Numbers enumerator. 
- typedef enum { + */ 
-       CERO, /**< Zero */ +typedef enum { 
-       UNO,  /**< One */ +      CERO, /**< Zero */ 
-       DOS   /**< Two */ +      UNO,  /**< One */ 
- } numeros; +      DOS   /**< Two */ 
- +} numeros; 
-[[Category: Guidelines]] +</code>
-[[Category: Español]]+
ºº