introducción a ngdocs

ngdocs, una herramienta muy buena para documentar proyectos angular.

Kandinsky

archivado en: JavaScript / 29 septiembre, 2015 / taller:

ngdocs es una herramienta muy potente para documentar proyectos angular. De hecho, es la que se usa en el propio framework. Está basada en js-docs y dgeni y permite generar una web a partir de determinados comentarios.

Para instalarlo, con el Node y el Grunt instalados, nos vamos por consola hasta el directorio en el que tenemos el package.json y ejecutamos el npm:

npm install grunt-ngdocs --save-dev

A continuación, abrimos el archivo Gruntfile y definimos la configuración. Algo así por ejemplo:

ngdocs: {

options: {

dest: 'docs',

html5Mode: false,

scripts: [

'bower_components/angular/angular.js'

]

},

api: {

src: ['app/**/*.js', '!app/**/*-spec.js'],

title: 'Docs'

}

},

Añadimos la tarea:

grunt.loadNpmTasks('grunt-ngdocs');

Y ahora si la ejecutamos por consola...

grunt ngdocs

... ale op! en el directorio docs se nos ha creado una web muy chula con la documentación del proyecto, tal y como podemos apreciar si comentamos alguna directiva en ngdoquesiano:

/**

* @ngdoc directive

* @name angularLab.directive:miDirectiva

*
* @description

* Soy una directiva formidable que hace cosas alucinantes

*

* @example

<mi-directiva foo="bar" />

*/

angular.module('angularLab').directive('miDirectiva', function() {

return {

restrict: 'AE',

replace: true,

template: '<p>Oh la la!</p> '

}

});

(Ojo, en localhost hay que abrirla desde un server para evitar el cross-domain).

Bueno, pues comprendido el sistema en general, vamos con los detalles ^^

El scaffolding de angular-yeoman creo que trae por defecto ng-docs preparado.

 

Documentación ngdocs

ngdocs cuenta con varios tags o etiquetas para documentar el código, las cuales se caracterizan por ir precedidas por una @. Las más importantes son:

@ngdoc: es la primera que se incluye en la definición de los componentes angular y sirve para definir si lo que sigue es un controlador (controller), un servicio o factoría (service), un filtro (filter) o una directiva (directive).

@name: sirve para indicar el nombre del componente y es muy importante que siga esta sintaxis:

nombreMódulo.tipoComponente:nombreComponente

angularLab.controller:MainCtrl

A partir de este nombre, ngdocs generará las ramas y rutas internas de la web de la aplicación.

@description: una descripción del componente. Y aquí es un buen sitio para usar signos markdown, que sirven para dar formato html al contenido. El más útil en lo que nos atañe son los tres acentos inversos, que sirven para mostrar código:

* ```

function miFuncion () {

console.log("lala laa");

 }

* ```

Además, en las directivas personalizadas es habitual añadir estos tags:

@scope: se incluye para indicar que lleva un $scope aislado (y solo en ese caso).

@restrict: si la directiva es un elemento (e), un atributo (a) o una clase (c)

@param {tipo}: el tipo de parámetro que espera (@param {boolean} miParametro. Los tipos pueden ser string, object, array y boolean.

@example: Un ejemplo de cómo se implementaría.

Ya solo con esto sería formidable, pero es que también podemos documentar el desarrollo de un componente, es decir, los métodos (method) y las propiedades (property). Para eso, ya sea usando method o property y methodOf o propertyOf según sea el caso, la construcción suele ser algo así:

/**

* @ngdoc method

* @name miMetodo

* @methodOf angularLab.controller:MainCtrl

* @description

* Descripción de mi método

*

* @param {int} width el ancho de la página

* @returns {Array} Valores trabajados...

*/

Bueno, habría más temas que contar, como la posibilidad de añadir enlaces, páginas-tutoriales, las posibilidades del archivo de configuración, etcétera, pero espero que con lo expuesto baste para que quien esté interesado pueda profundizar a partir de la documentación del proyecto, pues yo por hoy lo dejo aquí.

|| Tags: ,

valoración de los lectores sobre introducción a ngdocs

  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración positiva
  • estrellica valoración negativa
  • 3.8 sobre 5 (4 votos)

¿Te ha parecido útil o interesante esta entrada?
dormido, valoración 1 nadapensativo, valoración 2 un poco sonrisa, valoración 3 a medias guiño, valoración 4 bastante aplauso, valoración 5 mucho

Tú opinión es muy importante, gracias por compartirla!

Los comentarios están cerrados.