una - ¿Cómo crear fácilmente el descuento amigable de Github para las funciones de JavaScript documentadas?

tipos de funciones en javascript

Question

Quiero poder tomar comentarios de JSDoc como este en cualquier parte de la fuente de JavaScript (incluso anidados varias capas de funciones, en un módulo o incluso en funciones anónimas):

/**
 *  Used to do some important thing that needs doing that works like xyz.
 *  @param {String} whatever - some string that has some purpose
 *  @param {Function} callback - a function that needs to be run
 *  @returns {Boolean} whether or not something happened
 */
 function something(whatever, callback) {
     ...

y tiene alguna manera fácil de producir un buen descuento:

##`root.something(whatever,callback)`
Used to do some important thing that needs doing that works like xyz.

*Parameters*
  `whatever {String}` some string that has some purpose
  `callback {Function}` a function that needs to be run

*Returns*
   `{Boolean}` whether or not something happened

Donde "raíz" es el espacio de nombre en el que se puede acceder a esa función. O si se trata de una función anónima o una función privada (que por alguna razón debería estar en doco público, ¿tiene sentido eso?), Use alguna otra convención para denotar eso. Tal vez

##_private_function_ `something(whatever,callback)`

  and

##_anonymous_function_`(whatever,callback)`

No tiene que ser exactamente ese formato, solo algo que se ve bien en Github y tiene sentido. La herramienta ideal sería lo suficientemente inteligente como para poder tomar código como Mustache.js y producir buenos resultados. Y lo mejor sería si puede manejar muchos archivos fuente y producir un documento como salida, o un conjunto de documentos vinculados dependiendo de la configuración.

Y sería mejor si esto se hiciera de una manera que se pueda incluir completa y fácilmente en un repositorio git para que las personas no tengan que configurar una cadena de herramientas altamente específica para actualizar el doco. O requiere una cadena de herramientas mínima al menos.

Ah, y un pony.

Opciones existentes

JSDoc , más algún tipo de conversión HTML -> markdown

JSDoc es bastante bueno. Pero parece que no puedo hacer que funcione bien con los módulos. O más bien, es una molestia más grande de lo que debería ser en mi humilde opinión. No debería necesitar agregar una etiqueta adicional para nombrar la función. Probé @export y @name y todavía tengo problemas para mostrarlo en el documento final de la manera que me gustaría. Si alguien puede señalar una fuente comentada de JSDoc que tiene módulos y está bien hecha, eso podría ayudar. Actualización: JSDoc v3 en realidad parece mucho mejor con módulos que v2, por lo que podría ser una mejor opción.

Incluso si pudiera obtener la salida JSDoc como quiero, necesitaría convertir de HTML a markdown. Parece que no puedo encontrar una buena herramienta para eso, ¿existe uno?

Docdown

Jugué un poco con Docdown pero el hecho de que es PHP es una especie de no arranque para mí ...

YUIDoc , más conversión

De hecho, no he jugado con YUIDoc pero se ve bien. Aún así, necesitaría un convertidor. ¿Se ocupa fácilmente de los módulos y evita tener que proporcionar el nombre de la función y exportar el nombre explícitamente?

Dox , más las plantillas de descuento

Dox produce JSON a medida que sale, por lo que debería casarlo con algunas buenas plantillas de rebajas, y además incluye un motor de plantillas para generar los documentos. ¿Alguien ha reunido un conjunto de tales plantillas de una manera útil?

jGrouse , más conversión

Se ejecuta con ANT. Siguiente...

ScriptDoc ...

¿Ya existe esto? Parece ser parte del estudio de Aptana por lo que sería un no arranque ... Aptana no parece tener ninguna información al respecto. Pero ScriptDoc.org tiene información interesante sobre crack, si es útil ...

Pdoc

Pdoc está basado en Ruby, pero esa cadena de herramientas no es poco común, así que no es un gran problema. Puede proporcionar sus propias plantillas, por lo que tal vez ya haya algunas buenas. No he jugado con eso ... ¿vale la pena? ¿Hay buenas plantillas de descuentos disponibles?

¿Algo más?

¿Qué más hay?

¡Haz lo tuyo!

Después de jugar con JSDoc durante unas horas tratando de hacer que funcione como yo quería, me di por vencido y escribí mi propia solución rápida y sucia en Java para CharFunk , una biblioteca de JavaScript unicode en la que he estado trabajando. Funciona lo suficientemente bien como para lo que necesito, aunque todavía no está cerca del objetivo general.

Asi que.....

¿Es esta una necesidad no satisfecha o solo soy yo?

Answer 1

DE ACUERDO. Después de deliberar un poco conmigo mismo, iría con DOX + Subrayado / Sea cual sea el motor de plantillas JS sobre Nodo.

Debería ser bastante simple. Posiblemente, incluso puedes entrar en Grunt o similar y ejecutarlo en una tarea de vigilancia.

Dox es, por lo que puedo recordar, relativamente ligero y tiene un paquete npm (IIRC).

ACTUALIZACIÓN: Creo que, después de un poco de experiencia, me gustaría cambiar mi respuesta a YUIDoc.

Answer 2

Intenta usar Verb . En el caso de uso más simple, Verb creará un archivo Léame a partir de una plantilla utilizando datos de package.json.

Pero el verbo también tiene características avanzadas si necesita generar TOCs de varias páginas o crear ayudantes personalizadas, etc.

En cuanto a la documentación de la API, consulte este archivo de ejemplo generado utilizando los comentarios de código de index.js . Haga clic en los títulos, los que se generan automáticamente también. Use este asistente incorporado para generar documentos API desde cualquier ruta de archivo especificada. También puede usar patrones globales para obtener documentos de múltiples archivos.

Verb construirá un .verb.md sin ninguna configuración. Pero si necesita más, puede usar un verbfile.js

Answer 3

Tuve la necesidad de crear una documentación de API de JSDoc que debería ser fácil de usar y también es compatible con las pilas frontend modernas. Algunas de las bibliotecas mencionadas tienen problemas con el código JS transpilado en babeljs, por lo tanto, debe transpilar su código con comentarios temporalmente solo para generar su documentación de descuento.

Para este caso de uso, encontré http://documentation.js.org/ bastante útil ya que tienen soporte integrado para las configuraciones de BabelJs, por lo que se encarga de generar el descuento (JSON, HTML) de sus JSDocs.

Answer 4

Yo uso github.com/75lb/jsdoc-to-markdown ..

escribir código documentado:

/**
a quite wonderful function
@param {object} - privacy gown
@param {object} - security
@returns {survival}
*/
function protection(cloak, dagger){}

obtener documentos de descuento:

$ jsdoc2md example/function.js

#protection(cloak, dagger)
a quite wonderful function

**Params**

- cloak `object` - privacy gown
- dagger `object` - security

**Returns**: `survival`

Estos proyectos tienen archivos readme renderizados por jsdoc2md :

• handbrake-js
• array-tools
• command-line-args

Answer 5

jsDox. https://github.com/sutoiku/jsdox Análisis completo usando UglifyJS

Mox. https://github.com/tjchaplin/mox Varios ejemplos / plantillas listos para ejecutarse.

Ambos manejan los formatos JSDoc / Dox. Ambos tienen desarrollo activo. Para mí, Mox gana debido a la suite de ejemplo.

Answer 6

markdox puede generar documentos de descuento a partir del código de JavaScript.

Answer 7

¿Has probado jsdox ?

Es un node.js jsdoc al generador de rebajas.