dojo js library + jsdoc -> cómo documentar el código?

Question

Me encantaría preguntarte cómo desarrollan la documentación los chicos que están desarrollando dojo?

A partir de las compilaciones nocturnas puede obtener los archivos js sin comprimir con todos los comentarios, y estoy seguro de que hay algún tipo de script de documentación que generará algún html o xml.

Supongo que usan jsdoc ya que esto se puede encontrar en su carpeta de utilidades, pero no tengo idea de cómo usarlo. jsDoc toolkit usa diferentes notaciones /**commenting**/ que los archivos dojo originales.

Gracias por toda su ayuda

Answer 1

se hace todo con un analizador de PHP personalizado y Drupal. Si mira en util/docscripts/README y util/jsdoc/INSTALL, puede obtener todos los detalles sangrientos sobre cómo generar los documentos.

Es diferente de jsdoc-toolkit o JSDoc (como usted ha descubierto).

FWIW, estoy usando jsdoc-toolkit ya que es mucho más fácil generar HTML estático y hay mucha documentación sobre las etiquetas en la página de códigos de google.

Además, solo para ser claros, no desarrollo el dojo en sí mismo. Simplemente lo uso mucho en el trabajo.

Answer 2

Hay dos partes en el proceso "dojo jsdoc". Hay un analizador, escrito en PHP, que genera xml y/o json de la totalidad de espacios de nombres listados (definidos en util/docscripts/modules, para que pueda agregar sus propios espacios de nombres. Hay instrucciones de uso básicas sobre el archivo "generate". php ") y una parte de Drupal llamada" jsdoc "que se instala como un módulo/plugin drupal/lo que sea.

El aspecto de Drupal es solo la vista básica de Dojo de esta información. Un XSLT bien hecho o algo para iterar sobre json y producir html funcionaría de la misma manera, aunque ninguno de estos se proporciona por defecto (¡me encantaría una contribución!). Me alejo del bit de Drupal, aunque se ha estado ejecutando en api.dojotoolkit.org desde hace un tiempo.

El analizador de documentos está expuesto, por lo que puede utilizar sus capacidades de inspección para escribir su propia salida personalizada también. Lo uso para generar la finalización del código .cix de Komodo en un archivo PHP [bastante descuidado] util/docscripts/makeCix.php, que vuelca la información tal como se encuentra en un documento XML diseñado para que coincida con la especificación allí. Esto podría modificarse para generar cualquier tipo de salida que elijas con un pequeño truco.

La sintaxis doc es todo lo definido en la página de guía de estilo: http://dojotoolkit.org/reference-guide/developer/styleguide.html