DocBlockr - Пакеты - Контроль пакетов

1. Монтаж
2. Покажи свою любовь
3. использование
4. Завершение докблока
5. Документация по функциям
6. Переменная документация
7. Расширение комментария
8. Оформление комментариев
9. Ремонт DocBlock
10. Переформатирование абзацев
11. Добавление дополнительных тегов
12. конфигурация
13. Авторы

DocBlockr - это пакет для Возвышенный текст 2 и 3 что делает написание документации на одном дыхании. DocBlockr поддерживает JavaScript (включая ES6), PHP , ActionScript , Haxe , CoffeeScript , TypeScript , Java , Apex , Groovy , Objective C , C , C ++ и Rust .

Монтаж

Контроль пакетов

1. Открыть управление пакетами: Настройки -> Управление пакетами
2. Выберите Управление пакетами: Установить пакет
3. Введите DocBlockr в поле поиска и выберите пакет для его установки

Запросы функций и отчеты об ошибках

Вы можете оставить любую из этих вещей Вот , Запросы на извлечение приветствуются от всей души, но, пожалуйста, прочитайте CONTRIBUTING.md первый! В основном: в этом репо развивается основная ветка разработки, а стабильная «производственная» ветка - мастер. Пожалуйста, не забывайте основывать свою ветку на разработке и отправлять запрос на получение обратно в эту ветку.

Покажи свою любовь

Изменения

• v2.14.1 , 17 августа 2015
  • Исправлена ​​ошибка деиндентирования с повторным анализом блоков документов.
• v2.14.0 , 15 июня 2015
  • Добавляет опцию jsdocs_function_description (спасибо Жерар Рош )
  • Лучшая обработка ошибок парсера (спасибо Жерару Роше)
• v2.13.3 , 4 июня 2015 г.
  • Сокращение массива PHP определено правильно (благодаря Жерар Рош )
  • Декорирование комментариев при использовании вкладок для отступов работает лучше (благодаря Джек Чернг )
• v2.13.2 , 30 марта 2015 г.
  • Обновлены автодополнения PHPDoc для соответствия новой спецификации (благодаря Жерар Рош )
  • Правильно обрабатывать случай, когда запятые появляются внутри имени типа в Java
  • Добавлена ​​ссылка на README в меню настроек
• v2.13.1 , 29 марта 2015 г.
  • Добавлена ​​поддержка языка Apex (спасибо @michacom )
  • Исправлены ошибки идентификации многомерных массивов в C / C ++
  • Исправляет переформатирование и повторный анализ докблоков в Java
  • Добавляет параметры для отключения:
  • открытие встроенного докблока с пробелом (jsdocs_quick_open_inline)
  • встроенное оформление комментариев (jsdocs_decorate)

Более старая история может быть найдена в файл истории ,

использование

Ниже приведены некоторые примеры того, что делает пакет. Обратите внимание, что для запуска этих завершений не нужны сочетания клавиш - просто напечатайте как обычно, и это произойдет за вас!

Завершение докблока

Нажатие клавиши ввода или табуляции после / ** (или ### * для Coffee-Script) приводит к появлению новой строки и закрытию комментария.

Блоки комментариев с одной звездочкой ведут себя аналогично:

Документация по функциям

Однако, если строка непосредственно после этого содержит определение функции, то ее имя и параметры анализируются, и некоторая документация добавляется автоматически.

Нажмите Tab для перемещения вперед по полям, нажмите Shift + Tab для перемещения назад по полям.

Если имеется много аргументов или длинных имен переменных, иногда полезно распределить аргументы по нескольким строкам. DocBlockr также обрабатывает эту ситуацию:

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

DocBlockr попытается сделать интеллектуальное предположение о возвращаемом значении функции.

• Если имя функции или начинается с «set» или «add», то нет @вернуть вставлен.
• Если имя функции или начинается с «is» или «has», то предполагается, что оно возвращает логическое значение.
• В Javascript, если функция начинается с заглавной буквы, предполагается, что эта функция является определением класса. нет @вернуть тег добавлен.
• В PHP некоторые из магические методы предварительно заполнить их значения:
  • __construct, __destruct, __set, __unset, __wakeup не имеют @вернуть тег.
  • __sleep возвращает массив.
  • __toString возвращает строку.
  • __isset возвращает bool.
• В ES6 Javascript функции генератора получают @Уступать тег вместо @вернуть

Переменная документация

Если строка, следующая за docblock, содержит объявление переменной, DocBlockr попытается определить тип данных переменной и вставить его в комментарий.

Нажмите пробел или Shift + Enter после открытия / **, чтобы вставить встроенный блок документов.

DocBlockr также попытается определить тип переменной по ее имени. Предполагается, что переменные, начинающиеся с is или has, являются логическими значениями, а callback, cb, done, fn и next - функциями. Если вы используете свою собственную систему именования переменных (например, венгерская нотация: все логические значения начинаются с b, массивы начинаются с arr), вы можете определить эти правила самостоятельно. Используйте параметр jsdocs_notation_map, пример:

{"jsdocs_notation_map": [{"prefix": "b", / * префикс, соответствует, только если за ним следует подчеркивание или AZ * / "type": "bool" / * переводится как "Boolean" в javascript, "bool "в PHP * /}, {" regex ":" tbl _? [Rr] ow ", / * любое произвольное регулярное выражение для проверки имени переменной * /" type ":" TableRow "/ * вы можете добавлять свои собственные типы * /}]}

Карта нотаций также может использоваться для добавления произвольных тегов в соответствии с вашими собственными соглашениями о коде. Например, если ваши соглашения гласят, что функции, начинающиеся с подчеркивания, являются частными, вы можете добавить это в jsdocs_notation_map:

Расширение комментария

Нажатие ввода внутри докблока автоматически вставит ведущую звездочку и сохранит ваш отступ.

Это относится к комментариям docblock / ** как это * / так же как к встроенным комментариям двойной косой черты // как это

В любом случае вы можете нажать shift + enter, чтобы остановить автоматическое продление.

Часто при документировании параметра или добавлении описания к тегу ваше описание будет охватывать несколько строк. Если линия, на которой вы находитесь, следует непосредственно за строкой тега, нажатие клавиши Tab переместит отступ в правильную позицию.

Оформление комментариев

Если вы напишите комментарий с двумя косыми чертами, а затем нажмете Ctrl + Enter, DocBlockr «украсит» эту строку за вас.

// Foo bar baz << Ctrl + Enter >> - становится ///////////////// // Foo bar baz // /////////// //////

Это можно отключить, изменив для параметра jsdocs_decorate значение false.

Ремонт DocBlock

Иногда вы выполняете какое-либо действие, которое очищает поля (фрагменты текста, по которым вы можете перемещаться, используя Tab). Таким образом, в DocBlock у вас будет несколько заполнителей, и вам будет нелегко перейти к ним.

С DocBlockr вы можете повторно проанализировать комментарий и повторно активировать поля, нажав горячую клавишу Alt + Shift + Tab в OS X или Linux или Alt + W в Windows

Переформатирование абзацев

Внутри блока комментариев нажмите Alt + Q, чтобы обернуть строки, чтобы они соответствовали вашим линейкам. Если вы хотите, чтобы последующие строки абзаца были с отступом, вы можете настроить параметр jsdocs_indentation_spaces_same_para. Например, значение 3 может выглядеть так:

/ ** * Duis sed arcu non Tellus Eleifend Ullamcorper Quis Non Erat. Curabitur * metus elit, ultrices et tristique a, blandit at justo. * @param {Строка} foo Lorem ipsum dolor sit amet. * @param {Number} бар Nullam Fringilla Feugiat Pretium. Quisque * contectetur, risus eu pellentesque tincidunt, nulla ipsum imperdiet * massa, sit amet adipiscing dolor. * @вернуть {[тип]} */

Добавление дополнительных тегов

Наконец, ввод @ внутри докблока покажет список завершения для всех тегов, поддерживаемых JSDoc , Google Closure Compiler , YUIDoc или же PHPDoc , Дополнительная помощь предоставляется для каждого из этих тегов путем предварительного заполнения аргументов, которые каждый ожидает. Нажатие Tab переместит курсор к следующему аргументу.

конфигурация

Вы можете получить доступ к настройкам конфигурации, выбрав Настройки -> Настройки пакета -> DocBlockr.

Префикс jsdocs_ * является наследием минувших дней ...

• jsdocs_indentation_spaces (Number) Число пробелов для отступа после ведущей звездочки.

  // jsdocs_indentation_spaces = 1 / ** * foo * / // jsdocs_indentation_spaces = 5 / ** * foo * /

• jsdocs_align_tags (String) Должны ли слова, следующие за тегами, совпадать. Возможные значения: «нет», «неглубоко» и «глубоко»

  Для обратной совместимости ложь эквивалентна «нет», истина эквивалентна «мелкой»

  «мелкий» будет выравнивать только первые слова после тега. например:

  'deep' будет выравнивать каждый компонент тегов, например:

• jsdocs_extra_tags (Array.String) Массив строк, каждая из которых представляет дополнительные шаблонные комментарии для добавления в функции . Они также могут включать произвольный текст (не только теги).

  // jsdocs_extra_tags = ['Это классная функция', ' @author nickf ',' @версия $ {1: [версия]} '] / ** << enter >> function foo (x) {} / ** * [foo description] * Это классная функция * @author ник * @версия [версия] * @param {[type]} x [description] * @вернуть {[type]} * / function foo (x) {}

  Здесь поддерживается базовая подстановка переменных для переменных date и datetime, заключенных в двойные фигурные скобки.

  // jsdocs_extra_tags = [' @Дата {{Дата}}', ' @anotherdate {{datetime}} '] / ** << enter >> function foo () {} / ** * [описание foo] * @Дата 2013-03-25 * @datetime 2013-03-25T21: 16: 25 + 0100 * @вернуть {[тип]} */

• jsdocs_extra_tags_go_after (Boolean) Если true, дополнительные теги помещаются в конец блока (после параметра / возврата). По умолчанию: false

• jsdocs_extend_double_slash (Boolean) Следует ли расширять комментарии с двойной косой чертой. Пример этой функции описан выше. По умолчанию: правда

• jsdocs_deep_indent (Boolean) Должен ли нажатие клавиши tab в начале строки в docblock отступать в соответствии с полем описания предыдущей строки. Пример этой функции описан выше. По умолчанию: правда

• jsdocs_notation_map (Array) Массив объектов обозначений. Каждый объект нотации должен определять либо префикс, либо свойство регулярного выражения, либо свойство типа.

• jsdocs_return_tag (String) Текст, который должен использоваться для @вернуть тег. По умолчанию, @вернуть используется, однако это можно изменить на @returns если вы используете этот стиль.

• jsdocs_spacer_between_sections (Boolean | String) Если true, то между разделами докблока вставляются дополнительные пустые строки. Если установлено значение "after_description", тогда разделитель будет добавлен только между описанием и первым тегом. По умолчанию: false.

• jsdocs_indentation_spaces_same_para (Number) Описано выше в разделе « Переформатирование абзацев ». По умолчанию: 1

• jsdocs_autoadd_method_tag (Boolean) Добавить @method тег к док-блокам функций. По умолчанию: false

• jsdocs_simple_mode (Boolean) Если true, DocBlockr не будет добавлять шаблон при создании блока документа перед функцией или переменной. Полезно, если вы не хотите писать в стиле Javadoc, но все же хотите, чтобы ваш редактор помогал при написании комментариев к блоку. По умолчанию: false

• jsdocs_lower_case_primitives (Boolean) Если true, примитивные типы данных добавляются в нижнем регистре, например, «число» вместо «число». По умолчанию: false

• jsdocs_short_primitives (Boolean) Если true, примитивы Boolean и Integer сокращаются до Bool и Int. По умолчанию: false

• jsdocs_newline_after_block (Boolean) Если true, после конца докблока добавляется дополнительный разрыв строки, чтобы отделить его от кода. По умолчанию ложь

• jsdocs_param_name (Boolean) Если true, имя параметра функции добавляется в шаблон. Если false, это опущено. По умолчанию: правда

• jsdocs_decorate (Boolean) Если false, отключите оформление однострочных комментариев с помощью Ctrl + Enter. По умолчанию: правда

• jsdocs_quick_open_inline (Boolean) Если true, встроенный докблок будет открыт при нажатии пробела после открывателя (/ **). При значении false их можно открыть, нажав Shift + Enter. По умолчанию: правда

• jsdocs_function_description (Boolean) Если true, для функций будет добавлена ​​строка описания. По умолчанию: правда

Авторы

Этот пакет был создан Ник Фишер , но имеет много вкладов от других. Пожалуйста, посмотрите на список участников чтобы увидеть, кто еще должен получить некоторое спасибо.

Похожие

Комментарии