c++ - otro - incluir header en c
Documentación del archivo de encabezado C/C++ (5)
Definitivamente tendré algo de documentación en los archivos de encabezado. 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).
Doxygen está bien por mi experiencia.
¿Cuál cree que es la mejor práctica al crear archivos de encabezado públicos en C ++?
¿Los archivos de encabezado no deben 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.
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?
Creo que Doxygen es la plataforma más común para generar documentación, y hasta donde 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 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 usa 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 los archivos fuente / encabezado. 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.
Esos son mis dos centavos.
Normalmente pongo documentación para la interfaz (parámetros, valor de retorno, lo que hace la función) en el archivo de interfaz (.h) y la documentación para la implementación ( cómo funciona la función) en el archivo de implementación (.c, .cpp, .metro).
Escribo un resumen 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.
Ponga suficiente en el código que pueda estar solo. 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 una forma que la mayoría de los editores reconozca es un bloque; para C ++ esto parece ser / * en lugar de //. De esa forma puedes doblarlo y solo ver las declaraciones.