JSDoc с AngularJS

В настоящее время в моем проекте мы используем JSDoc, мы недавно начали внедрять Angular, и я хочу продолжать использовать JSDoc, чтобы гарантировать, что вся документация находится в одном месте.

Я взглянул на людей, которые просто говорят, что используют ngDoc, но это не очень эффективный вариант, так как у нас всегда будет отдельный JavaScript, и я идеально бы все вместе.

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

В настоящее время это то, что у меня есть, но я не могу разместить документацию для run() каких-либо идей?

Ответ 1

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

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

 /**
  * @namespace angular_module
  */

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

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

 /**
  * @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 файле страницы MyController html. Строка полного пути, разделенная точками, создает соединение.

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

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

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

Кроме того, вы можете определить пространства имен, чтобы добавить иерархическую структуру. Например, вы можете определить пространство имен для включения всех контроллеров
```
/**
 * @namespace MyApp.Controllers
 */
```

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

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

Это просто;
Сохранена иерархия модуля-контроллера;
И он сохраняет достоинства 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

Что это.

Ответ 2

Мне пришлось спуститься по пути создания функций вне указанного выше типа и вызвать эти функции в таких вещах, как .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);
})();