JSDoc с AngularJS

Я тоже столкнулся с этой проблемой. Сейчас я пишу документацию для кодов angularjs с помощью комментариев jsdoc, например:

1.Создайте пустой файл .js со следующим комментарием:

 /**
  * @namespace angular_module
  */

Это создаст отдельный html в сгенерированной документации для перечисления всех модулей.

2. В файлах javascript, определяющих любой новый угловой модуль, используйте такой комментарий

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

Это добавит элемент в приведенный выше список всех angular_modules, а также создаст отдельную html-страницу для MyModule, потому что это класс.

3. Для каждой службы angularjs используйте следующий комментарий:

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

Это добавит элемент на страницу MyModule для службы. Поскольку он добавлен как функция, вы можете написать документацию для входных параметров, используя @param, и возвращаемых значений, используя @return.

4. Если у меня есть довольно длинные коды в контроллере или директиве MyModule и я хочу иметь отдельный html-файл для его документирования, я буду аннотировать контроллер или директиву как класс, используя полный путь. например

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

Таким образом, MyController будет указан как один элемент на странице документации MyModule.

Затем мы можем аннотировать код внутри контроллера как функции-члены MyController.

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

Таким образом, документация по этой функции появится в html-файле html-страницы MyController. Полная строка пути, разделенная точками, создает соединение.

Существует три типа синтаксиса для namepath:

• Person#say // метод экземпляра с именем «say».
• Person.say // статический метод с именем «say».
• Person~say // внутренний метод с именем «say».

Тем не менее, один несовершенный момент комментирования контроллера как класса заключается в том, что «новый» будет найден перед именем контроллера в сгенерированной html-документации, поскольку он описан как конструктор класса.

5. Кроме того, вы можете определить пространства имен, чтобы добавить иерархическую структуру. Например, вы можете определить пространство имен, включающее все контроллеры.

   /**
    * @namespace MyApp.Controllers
    */
   

, и добавьте ко всем контроллерам префикс MyApp.Controllers. Вы также можете определить пространства имен, такие как MyApp.Product или MyApp.Customer и т. д.

Хотя это и не идеально, мне нравится использовать jsdoc для документирования кода angularjs, потому что

1. Это просто;
2. Иерархия модуль-контроллер-функция сохраняется;
3. И это сохраняет достоинство jsdoc в том, что это сайт с доступной для просмотра документацией.

Таблица стилей jsdoc в виде таблицы:

В частности, я адаптировал таблицу стилей jsdoc по умолчанию к стилю таблицы, такому как документация Java API. Это выглядит яснее.

В Windows я заменяю этот файл: C:\Users\user1\AppData\Roaming\npm\node_modules\jsdoc\templates\default\static\styles этим файлом https://github.com/gm2008/jsdoc/blob/master/templates/default/static/styles/jsdoc-default.css

Вот и все.

Мне пришлось пойти по пути создания функций вне указанного выше типа и вызова этих функций в таких вещах, как .run или фабрики и т. д.

/**
 * @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);
})();