C/C++ archivo de Encabezado de la documentación [cerrado]

Question

¿Cuál crees que es la mejor práctica a la hora de crear pública de los archivos de cabecera en C++?

1. Debe encabezado de los archivos no contienen, breve o masivas de documentación?He visto de todo, desde casi ninguna documentación (apoyándose en algunos documentación externa) a grandes especificaciones de invariantes, parámetros válidos, valores de retorno, etc.No estoy seguro exactamente lo que yo prefiero, documentación es bueno ya que siempre he acceso a ella a partir de su editor, en la otra mano un archivo de encabezado con muy breve documentación puede mostrar una interfaz completa en una o dos páginas de texto dando una mejor visión de lo que es posible hacer con una clase.

2. Digamos que yo vaya con algo como breve o masivas de documentación.Quiero algo similar a javadoc donde puedo documento de devolución de los valores, parámetros, etc.¿Cuál es el mejor convenio para que en c++?Tan lejos como puedo recordar doxygen hace cosas buenas con java doc estilo de documentación, pero hay otros convenios y herramientas para esto debo tener en cuenta antes de ir para javadoc estilo de documentación?

Answer 1

Normalmente pongo documentación para la interfaz (parámetros, valor de retorno, qué hace la función) en el archivo de interfaz (.h) y la documentación para la implementación ( cómo la función sí) en el archivo de implementación (.c, .cpp, .m).

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

La herramienta que uso es Doxygen.

Answer 2

1. Definitivamente tendría algo de documentación en los archivos de encabezado. Mejora enormemente la depuración al tener la información al lado del código, y no en documentos separados. Como regla general, documentaría la API (valores de retorno, argumento, cambios de estado, etc.) junto al código, y vistas generales de arquitectura de alto nivel en documentos separados (para dar una visión más amplia de cómo se junta todo; es difícil de 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

Creo Doxygen es el más común de plataforma para la generación de la documentación, y hasta donde yo sé, es más o menos capaz de cubrir JavaDoc-notación (no limitada a, por supuesto).He usado doxygen para C, con ACEPTAR los resultados, yo creo que es más adecuado para C++, aunque.Es posible que desee buscar en robodoc así, aunque creo que la Navaja de Occam que te diga que en lugar de ir por Doxygen.

Respecto a la cantidad de documentación, nunca he sido una documentación-ventilador de mí mismo, pero si me gusta o no, tener más documentación siempre mejor que tener ninguna documentación.Me gustaría poner el API-documentación en el archivo de encabezado, y la documentación de la implementación en la implementación (lógico, ¿no?).:) De esa manera, IDEs tienen la oportunidad de recoger y mostrar durante la función de autocompletar (Eclipse hace esto para JavaDocs, por ejemplo, tal vez también por doxygen?), que no debe ser subestimado.JavaDoc tiene esta peculiaridad de que se utiliza la primera frase (es decir,hasta la primera parada total) como una breve descripción, no sé si la Doxygen hace esto, sin embargo, pero si es así, debe ser tomado en cuenta en la preparación de la documentación.

Tener una gran cantidad de documentación que se corre el riesgo de estar fuera de fecha, sin embargo, la conservación de la documentación, cerca de el código da a las personas una oportunidad para mantenerlo actualizado, por lo que sin duda debe mantener en la fuente/archivos de encabezado.Lo que no debe ser olvidado es la producción de documentación.Sí, algunas personas usan la documentación directamente (a través de la IDE o lo que sea, o simplemente leer el archivo de encabezado), pero algunas personas prefieren otras formas, así que probablemente debería considerar la posibilidad de poner su (actualizado regularmente) documentación de la API en línea, todo agradable y navegable, así como, quizás, la producción de el hombre de los archivos si usted está apuntando a *nix-en base a los desarrolladores.

Que mis dos centavos.

Answer 4

Pon suficiente en el código para que pueda estar solo. Casi todos los proyectos en los que he estado donde la documentación estaba separada, se desactualizó o no se realizó, en parte porque si se trata de un documento separado se convierte en una tarea separada, en parte porque la administración no lo permitió como tarea en presupuesto. 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 reconocen que es un bloque; para C ++ esto parece ser / * en lugar de //. De esa manera puedes doblarlo y solo ver las declaraciones.

Answer 5

Quizás le interesaría gtk-doc . Puede ser & Quot; un poco incómodo configurar y usar & Quot; pero puede obtener una buena documentación de la API del código fuente, con este aspecto:

Funciones de utilidad de cadena