JavaScript Código autocomnable ¿Dónde están las herramientas de documentos de API?

Question

Estos dos conceptos parecen contradictores. Hay un lado del argumento que ve el daño que los comentarios hacen a la legibilidad y las violaciones de la seca (si los comentarios se mantienen actualizados). Sin embargo, voltee la moneda y es necesario proporcionar una buena documentación de API para su código para que otros puedan usar sus bibliotecas.

Cada herramienta (JSDOC, PDOC, etc.) que he visto que está diseñada para generar documentos API utiliza una cantidad extrema de espacio para proporcionar esa documentación. Necesito proporcionar documentación de la API, lo que no necesito es que la mitad de mi loc de mi LOC esté especialmente formateado comentando para que JSDOC pueda leerlo.

Actualmente estoy considerando una herramienta básica de Markdown como Jekyll y poner esta documentación en la carpeta A /DOC, eliminándola totalmente de mi código. ¿Alguien más ha encontrado un enfoque de este problema que les ha funcionado?

Answer 1

Esfinge es una herramienta de documentación para muchos idiomas, que supone que escribirá su documentación principalmente en archivos externos. Todavía tiene un autodoc Extensión que le permite extraer documentación de los comentarios en el código.

Personalmente, me parece más conveniente tener la documentación de la API cerca del código, ya que me ayuda a mantenerla actualizada. Además, otras personas que trabajan en ese código podrán tener la documentación justo cuando la necesiten, sin tener que explorar archivos externos. Francamente, no veo nada malo en tener la mayoría de las líneas de código que son comentarios: los editores generalmente colorean los comentarios de manera diferente y le permiten ignorarlos si lo desea.