C/C++ Documentación del archivo de encabezado

Question

¿Cuál cree que es la mejor práctica al crear archivos de encabezado públicos en C++?

1. ¿Los archivos de cabecera no deberían contener documentación breve o masiva? He visto todo, desde casi ninguna documentación (dependiendo de documentación externa) hasta grandes especificaciones de invariantes, parámetros válidos, valores de retorno, etc. No estoy seguro de qué es lo que prefiero, la gran documentación es buena ya que siempre tiene acceso a de su editor, por otro lado, un archivo de encabezado con documentación muy breve a menudo puede mostrar una interfaz completa en una o dos páginas de texto que ofrece una visión general mucho mejor de lo que es posible hacer con una clase.

2. Digamos que voy con algo así como documentación breve o masiva. Quiero algo similar a javadoc donde documente los valores devueltos, los parámetros, etc. ¿Cuál es la mejor convención para eso en C++? Por lo que puedo recordar, doxygen hace cosas buenas con la documentación de estilo doc de Java, pero ¿hay otras convenciones y herramientas para esto que deba tener en cuenta antes de ir a la documentación de estilo javadoc?

Answer 1

Por lo general ponen documentación de la interfaz (parámetros, valor de retorno, lo que hace la función) en el archivo de interfaz (.h), y la documentación de la aplicación ( cómo hace la función) en la implementación archivo (.c, .cpp, .m).

Escribo una descripción general de la clase justo antes de su declaración, por lo que el lector tiene información básica inmediata.

La herramienta que uso es Doxygen.

Answer 2

1. duda me volvería a tener algún tipo de documentación en los archivos de la cabecera de sí mismos. Mejora enormemente la depuración para tener la información al lado del código, y no en documentos separados. Como regla general, documentaría la API (valores de retorno, argumentos, cambios de estado, etc.) junto al código y las descripciones arquitectónicas de alto nivel en documentos separados (para ofrecer una visión más amplia de cómo se combinan todas las cosas; difícil colocar esto junto con el código, ya que generalmente hace referencia a varias clases a la vez).

2. Doxygen está bien desde mi experiencia.

Answer 3

Ponga suficiente en el código que puede ser independiente. Casi todos los proyectos en los que he estado donde la documentación estaba separada, se han quedado obsoletos o no, en parte, si se trata de un documento separado, se convierte en una tarea separada, en parte porque la administración no lo permite como una tarea en presupuestar Documentar en línea como parte del flujo funciona mucho mejor en mi experiencia.

Escriba la documentación en un formulario que la mayoría de los editores reconocen es un bloque; para C++ esto parece ser/* en lugar de //. De esa forma puedes doblarlo y solo ver las declaraciones.

Answer 4

Quizás se interese en gtk-doc. Puede ser "un poco difícil de configurar y usar", pero se puede obtener una documentación de la API agradable desde el código fuente, con este aspecto:

String Utility Functions

Answer 5

Creo Doxygen es la plataforma más común para la generación de documentación y por lo que yo sé, es más o menos capaz de cubrir la notación JavaDoc (no se limita, por supuesto).He usado doxygen para C, con resultados OK, creo que es más adecuado para C++. Es posible que desee examinar robodoc también, aunque creo que la Navaja de Occam le dirá que prefiera ir a Doxygen.

Respecto a la cantidad de documentación, nunca he sido un fanático de la documentación, pero me guste o no, tener más documentación siempre es mejor que no tener documentación. Pondría la documentación de la API en el archivo de encabezado y la documentación de implementación en la implementación (es lógico, ¿no?). :) De esta manera, los IDEs tienen la oportunidad de recogerlo y mostrarlo durante el autocompletado (Eclipse hace esto para JavaDocs, por ejemplo, ¿quizás también para doxygen?), Que no debe subestimarse. JavaDoc tiene esta peculiaridad adicional de que utiliza la primera oración (es decir, hasta el primer punto) como una breve descripción, pero no sabe si Doxygen lo hace, pero si es así, debe tenerse en cuenta al escribir la documentación.

Tener una gran cantidad de documentación corre el riesgo de estar desactualizado, sin embargo, mantener la documentación cerca del código le dará a la gente la oportunidad de mantenerlo actualizado, por lo que definitivamente debe mantenerlo en el código fuente/encabezado archivos. Lo que no se debe olvidar es la producción de documentación. Sí, algunas personas usarán la documentación directamente (a través del IDE o lo que sea, o simplemente leyendo el archivo de encabezado), pero algunas personas prefieren otras formas, por lo que probablemente debas considerar poner en línea tu documentación de API (regularmente actualizada), todo bien y navegable , y quizás también produzca archivos man si se dirige a desarrolladores * nix.

Esa es mi granito de arena.