Quiero ser capaz de tomar comentarios JSDoc como este en cualquier lugar en código JavaScript (incluso anidado en varias capas de funciones, en un módulo o incluso 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 tener alguna manera fácil de producir un buen markdown:

##`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 "root" es el espacio de nombres en el que se puede acceder a esa función. O si es una función anónima o una función privada(que por alguna razón debería estar en doco público, ¿eso tiene sentido??), utilice algún otro 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 vea bien en Github y tenga sentido. La herramienta ideal sería lo suficientemente inteligente como para ser capaz de tomar código como Bigote.js y producir un buen rendimiento. Y extra bueno sería si puede manejar una gran cantidad de archivos de origen y producir un documento como salida, o un conjunto vinculado de documentos dependiendo de la configuración.

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

Oh, y un pony.

Opciones existentes

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

JSDoc es bastante bueno. Pero 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 al nombre función. He probado el @ export y @name y todavía tengo problemas para que aparezca en el documento final de la manera que me gustaría. Si alguien puede apuntar a una fuente comentada 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 esto podría ser un mejor ajuste.

Incluso si pudiera obtener la salida JSDoc como quiero, tendría que convertir de HTML a markdown. No puedo encontrar una buena herramienta para eso. ¿existir?

Docdown

Jugué un poco con Docdown, pero el hecho de que sea PHP es una especie de nonstarter para mí...

YUIDoc, más conversión

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

Dox, más plantillas de descuento

Dox produce JSON como su salida, entonces tendrías que combinar eso con algunas buenas plantillas de markdown, y además incluir 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

Corre con ANT. Siguiente...

ScriptDoc...

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

Pdoc

Pdoc está basado en Ruby, pero esa cadena de herramientas no es infrecuente, por lo que no es un gran problema. Puede proporcionar sus propias plantillas, por lo que tal vez ya haya algunas buenas. No he jugado con él... vale la pena? ¿Existen buenas plantillas de markdown?

Algo más?

¿Qué más hay ahí fuera?

Haga su propio!

Después de jugar con JSDoc por unos pocos horas tratando de hacer que funcione como quería, me rendí y escribió mi propia solución rápida y sucia en Java para CharFunk, una biblioteca JavaScript unicode en la que he estado trabajando. Funciona lo suficientemente bien para lo que necesito, aunque aún no está cerca del propósito general.

So.....

¿Es esto una necesidad insatisfecha o es solo yo?