Мне было трудно документировать мою директиву angularJS, https://github.com/allenhwkim/angularjs-google-maps. Ниже приведен список инструментов документации, которые я пробовал и создавал.
1. документальный
Красиво, но не просто
Мы можем следовать этому руководству, а затем запустить этот документ для создания документации.
Плюсы:
- Он генерирует точно такой же стиль документации AngularJS из вашего кода.
- Он следует той же маркировке, что и код AngularJS.
- Клон механизма документирования AngularJS
Минусы:
- Нужно запустить сервер, чтобы увидеть документацию
- Зависит от ворчания и ворчания-документа
- Требуется конфигурация grunt-docular
- Так много пользовательских тегов для изучения
- и больше конфигурации, tl;dr
2. JSDoc
Просто, но не красиво
Плюсы:
- Для просмотра документации сервер не требуется
- Доступна командная строка
Минусы:
- группировать по классам, модулям и т. д., но не группировать по контроллерам, директивам, фильтрам и т. д.
- Без шикарного выхода. то есть http://gitgrimbo.github.io/jsdoc3-examples/jsdoc/
3. джени
Dgeni — генератор документации, разработанный командой Angular.
плюсы:
- семейство angularjs использует это; angularjs, транспортир и ионный
минусы:
- сложный; ни руководства, ни учебника, ни документации
- так много шагов; 14 шагов генерации документа(плюсы?)
4. Заключение Аллена
Почему мы не можем использовать простой генератор документации, такой как javaDoc? JSDoc работает как javaDoc, но не настроен для AngularJS. Затем, если я настрою JSDoc для AngularJS с помощью плагина и шаблона….?
Хорошо, позвольте мне сделать этот шаблон и плагин для AngularJS,
…. Неделю спустя,
Тада ~~
Плюсы:
- Это просто шаблон JSDoc, разработанный для AngularJS.
- Использование всех возможностей JSDoc Simplicity
- группировать по значениям тега @ngdoc; контроллер, директива, служба или любой другой
Минусы:
- Все равно не красивый дизайн
- Может быть, больше, о чем я не думаю в данный момент
Я бы хотел, чтобы это помогло тем, кто хочет документировать код AngularJS.
Аллен
