angularjs - returns - jsdoc recursive

JSDoc con AngularJS

Question

Actualmente, dentro de mi Proyecto, estamos usando JSDoc, recientemente comenzamos a implementar Angular y quiero seguir usando JSDoc para asegurar que toda la documentación esté en el mismo lugar.

He echado un vistazo a la gente que dice simplemente usar ngDoc, pero esta no es realmente una opción viable, ya que siempre tendremos un JavaScript separado y lo ideal sería tenerlo todo junto.

/**
 * @author Example <[email protected]>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;

    /**
     * A Example Angular Bootstrap Module
     * @module exampleAngularBootstrap
     */
    exAngular.bootstrap = angular.module(''exampleAngularBootstrap'', [
            ''ngRoute'',
            ''ngResource'',
            ''ngCookies''
        ])
        .run(function ($http, $cookies) {
            $http.defaults.headers.post[''X-CSRFToken''] = $cookies.csrftoken;
            $http.defaults.headers.common[''X-CSRFToken''] = $cookies.csrftoken;
        });
})();

Actualmente esto es lo que tengo, pero no puedo poner documentación para la ejecución () ¿alguna idea?

Answer 1

He tenido que ir por el camino de crear las funciones fuera del tipo anterior y llamar a esas funciones en cosas como .run o fábricas, etc.

/**
 * @author Example <[email protected]>
 * @copyright 2014 Example Ltd. All rights reserved.
 */
(function () {
    window.example = window.example || {};
    /**
     * Example Namespace
     * @memberOf example
     * @namespace example.angular
     */
    window.example.angular = window.example.angular || {};
    var exAngular = window.example.angular;
    /**
     * My example bootstrap run function
     * @param  {object} $http    {@link http://docs.angularjs.org/api/ng.$http}
     * @param  {[type]} $cookies {@link http://docs.angularjs.org/api/ngCookies.$cookies}
     */
    var runFunction = function ($http, $cookies) {
        $http.defaults.headers.post[''X-CSRFToken''] = $cookies.csrftoken;
        $http.defaults.headers.common[''X-CSRFToken''] = $cookies.csrftoken;
    };

    /**
     * A Example Angular Bootstrap Module
     * @memberOf example.angular
     * @namespace example.angular.bootstrap
     * @function bootstrap
     * @example
     *     &lt;div ng-app="exampleAngularBootstrap"&gt;
     *         &lt;div ng-view&gt;&lt;/div&gt;
     *     &lt;/div&gt;  
     */
    exAngular.bootstrap = angular.module(''exampleAngularBootstrap'', [
            ''ngRoute'',
            ''ngResource'',
            ''ngCookies''
        ])
        .run(runFunction);
})();

Answer 2

También he encontrado este problema. Ahora estoy escribiendo documentación para códigos angularjs a través de comentarios jsdoc como este:

1.Haga un archivo .js en blanco con el siguiente comentario:

 /**
  * @namespace angular_module
  */

Esto creará un html separado en la documentación generada para enumerar todos los módulos.

2. En los archivos javascript que definen cualquier módulo angular nuevo, use este tipo de comentario

 /**
  * @class angular_module.MyModule
  * @memberOf angular_module    
  */

Esto agregará un elemento en la lista anterior de todos los módulos de ángulos, así como la creación de una página html separada para MyModule, porque es una clase.

3. Para cada servicio angularjs, use el siguiente comentario:

 /**
  * @function myService
  * @memberOf angular_module.MyModule
  * @description This is an angularjs service.
  */

Esto agregará un elemento en la página MyModule para el servicio. Debido a que se agrega como una función, puede escribir documentación para los parámetros de entrada usando ''@param'' y devolver los valores usando ''@return''.

4. Si tengo códigos bastante largos en un controlador o directiva de MyModule y quiero tener un archivo html separado para documentarlo, anotaré el controlador o la directiva como una clase que usa la ruta completa. p.ej

 /**
  * @class angular_module.MyModule.MyController
  */

De esta manera, MyController aparecerá como un elemento en la página de documentación de MyModule.

Luego, podemos anotar códigos dentro del controlador como funciones miembro de MyController.

 /**
  * @name $scope.aScopeFunction
  * @function
  * @memberOf angular_module.MyModule.MyController
  * @description
  */

De esta manera, la documentación de esta función aparecerá en el archivo html de la página html de MyController. La cadena de ruta de acceso completa separada por puntos construye la conexión.

Hay tres tipos de sintaxis para la ruta de acceso:

• Person # say // el método de instancia llamado "say".
• Person.say // el método estático llamado "decir".
• Persona ~ decir // el método interno llamado "decir".

Sin embargo, un punto imperfecto de comentar el controlador como clase es que se encontrará un "nuevo" antes del nombre del controlador en la documentación html generada porque se describe como constructor de clase.

5. Además, puede definir espacios de nombres para agregar una estructura jerárquica. Por ejemplo, puede definir un espacio de nombres para incluir todos los controladores

   /**
    * @namespace MyApp.Controllers
    */

, y prefijo todos los controladores con MyApp.Controllers . También puede definir espacios de nombres como MyApp.Product o MyApp.Customer etc.

Aunque no es perfecto, me gusta usar jsdoc para documentar códigos angularjs porque

1. Es simple;
2. La jerarquía módulo-controlador-función se mantiene;
3. Y mantiene el mérito de jsdoc de que es un sitio de documentación navegable.

Una tabla de estilo jsdoc hoja de estilo:

En particular, he adaptado la hoja de estilo jsdoc predeterminada a un estilo de tabla como la documentación de la API de Java. Se ve más claro.

En Windows, sustituyo este archivo: C:/Users/user1/AppData/Roaming/npm/node_modules/jsdoc/templates/default/static/styles con este archivo https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

Eso es.