gifts2017

1cdoc - генератор документации для 1с

Опубликовал Ярослав Волохов (YVolohov) в раздел Программирование - Инструментарий

Предлагаю вниманию сообщества реализацию генератора документации для встроенного языка 1с...

О программе

                Генераторы документации это разновидность программ, позволяющих автоматизировать создание документации исходного кода. Одним из наиболее известных генераторов документации является Javadoc, ставший фактически стандартом для документирования кода на языке Java. Построение документации происходит на основании синтаксических конструкций языка программирования и специальных комментариев, которые должны соответствовать четко определенному стандарту, чтобы быть доступными для машинной обработки.

                 Преимущества хорошо документированного кода очевидны:

- при совместной разработке сокращаются затраты времени разработчиков на разбор кода, созданного коллегами, или собственного кода значительной давности;

- при вхождении в проект новых разработчиков сокращаются затраты времени на их адаптацию;

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

                В 1с давно назрела потребность для возникновения стандарта документирования API конфигураций и собственного генератора документации. Но кроме шаблона текста «Функция (с заголовком)», позволяющего описывать параметры и возвращаемое значение подпрограммы, ничего в этом плане так и не появилось. Тогда я решил создать собственный стандарт и генератор документации. Он получил название 1cdoc, по аналогии с Javadoc – аналогичной утилитой для языка Java.

 

Применение

                Документирование кода осуществляется при помощи специальных комментариев, которые должны начинаться с символов //** или //*. Обычные комментарии могут также свободно использоваться в документируемом модуле. Они никак не влияют на документацию.

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

                Комментарии, начинающиеся с символов //*, используются для описания переменных, функций или процедур и должны находится перед описываемыми объектами.

                Внутри документирующих комментариев используются дескрипторы. На данный момент в системе 1cdoc существуют следующие дескрипторы: @name, @desc, @author, @var, @param, @return.  Назначение каждого дескриптора описано в следующей таблице:

Дескриптор

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

@name

Имя модуля

@desc

Описание модуля, блока переменных, функции, процедуры

@author

Автор модуля

@var

Описание отдельной переменной

@param

Описание параметра функции или процедуры

@return

Описание возвращаемого значения функции

 

 

Пример

Пример документирования кода для последующей обработки 1cdoc приведен ниже:

 

//** @name Демонстрационный модуль 1cdoc
//** @desc пример описания кода в комментариях для последующего
//** создания документации с помощью генератора документации 1cdoc
//** @author Ярослав Волохов

//* @desc блок тестовых переменных
//* @var ДниНеделиМассив {Массив} хранит строчные представления дней недели
Перем ТекущийДеньНедели, ДниНеделиСтрока, ДниНеделиМассив Экспорт;

//* @desc конвертирует строку с разделителями в массив
//* @param пСтрока {Строка} исходная строка
//* @param пРазделитель {Строка} разделитель строки
//* @return {Массив} массив, ячейки которого хранят части строки
Функция СтрокаСРазделителямиВМассив(пСтрока, пРазделитель = ";") Экспорт

    Результат           = Новый Массив();
    МногострочнаяСтрока = СтрЗаменить(пСтрока, ";", Символы.ПС);
    ЧислоСтрок          = СтрЧислоСтрок(МногострочнаяСтрока);

    Для Счетчик = 1 По ЧислоСтрок Цикл
        ТекущаяПодстрока = СтрПолучитьСтроку(МногострочнаяСтрока, Счетчик);
        Результат.Добавить(ТекущаяПодстрока);
    КонецЦикла;

    Возврат Результат;

КонецФункции

//* @desc тест использования функции СтрокаСРазделителямиВМассив()
Процедура Тест()

    ДниНеделиСтрока = "Пн;Вт;Ср;Чт;Пт;Сб;Вс";
    ДниНеделиМассив = СтрокаСРазделителямиВМассив(ДниНеделиСтрока);
    Сообщить(ДниНеделиМассив[1]);
    Сообщить(ДниНеделиМассив[3]);

КонецПроцедуры

 

После обработки этого модуля 1сdoc построит отчет по документации в формате mxl, пример которого можно увидеть на скриншоте ниже (Скриншот №1).

 

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

                Для программной работы с 1cdoc используйте следующие экспортные функции, вызываемые из модуля объекта обработки:

ПолучитьСтруктуруМодуля() – принимает исходный код модуля в виде строки, парсит его, возвращает документацию в виде сложной структуры;

СоздатьОписаниеМодуляВФорматеMXL() – принимает структуру документации, возвращенную предыдущей функцией, возвращает готовую документацию в виде табличного документа.

                 Подробное описание этих функций есть модуле объекта обработки.

 

Полная (коммерческая) версия программ

                Функционал полной версии программы включает следующие дополнительные возможности:

- в документации добавлены поля со списками вызывающих и вызываемых подпрограмм каждой процедуры или функции в пределах модуля (Скриншот №2);

- добавлен дополнительный отчет по вызовам процедур и функций, который позволяет смоделировать и вывести в виде отчета любое возможное состояние стека вызовов с подробным описанием подпрограмм в стеке (Скриншот №3).

Скачать файлы

Наименование Файл Версия Размер Кол. Скачив.
1cdoc (демо)
.epf 41,07Kb
14.05.13
49
.epf 41,07Kb 49 Бесплатно
1cdoc - генератор документации для 1с (Полная версия)
23.05.2014
4000 руб.

См. также

Подписаться Добавить вознаграждение

Комментарии

1. Алексей 1 (AlX0id) 14.05.13 14:30
Однако, хотелось бы видеть возможность редактирования параметров из обработки :) А то не понятно, откуда они должны появляться в тексте программы..
2. Ярослав Волохов (YVolohov) 14.05.13 14:44
(1) В принципе можно. Правда в Javadoc и других подобных инструментах описание параметров вносится непосредственно в код на этапе его создания или изменения. Отдельных редакторов для этого нет.
3. Евгений Сосна (pumbaE) 15.05.13 09:36
Практическое применение?
Как применяете, как часто актуализируете документацию, формируется ли какая-либо wiki по распарсеному модулю?

То, что есть такая обработка - хорошо, но подскажите где можно потом использовать данную документацию. Какие преимущества несет она 1Снику, что бы заставить вести эти данные?
4. Алексей Лустин (lustin) 15.05.13 10:02
(0) и что значит "демо". В будущем планируется продажа ?
5. Ярослав Волохов (YVolohov) 15.05.13 10:43
(3) Пока что есть только парсер с возможностью вывода готовой документации в MXL. В ближайшем будущем планирую сделать вывод документации в формат HTML, чтобы можно было публиковать в интернете или цеплять к объектам конфигурации как справочную информацию 1с. Насчет wiki не понял вопроса, к сожалению с wiki-движками практически не работал (разве что вручную иногда корректировал статьи).
Практически пока не применял, ну кроме документирования самой обработки. Но думаю возможности очень широкие. В первую очередь это описание библиотек кода в общих модулях, код которых можно многократно использовать.
(4) Да, готовлю коммерческую версию с более широкими возможностями. В частности там будет поиск вызовов функций и процедур (т.е. список вызывающих и список вызываемых каждой функции или процедуры).
6. Александр Орефков (orefkov) 15.05.13 11:47
Имхо, тут важна не сама по себе эта конкретная обработка.
Более важным мне кажется создание СТАНДАРТА по документированию кода 1С.
Чтобы разные разработчики придерживались одних правил такого документирования.
Для снегопата очень давно уже хочу сделать подобную систему, останавливала необходимость все тщательно продумать. Ну и еще что не нравится в подобного рода документации - необходимость дублирования в комментариях имен (переменных, параметров), которые уже и так есть в коде. Ибо где дублирование - там и расхождения и поддержка актуальности. Хорошо хоть имена методов само выцепляет.
7. Ярослав Волохов (YVolohov) 15.05.13 12:11
(6) Если не указывать имена переменных и параметров, то единственный вариант это сопоставление по порядку. А так как количество и порядок параметров/переменных может изменятся (а документацию при этом могут забывать корректировать) то возрастает вероятность запутывания. Описания будут сопоставлены не со своими параметрами/переменными. Так что дублирование это наверное все же меньшее зло. Ну и в javadoc тоже оно присутствует. Вот например описание функции в java:

  /**
  * @param theFromFile Вертикаль, на которой находится фигура (1=a, 8=h)
  * @param theFromRank Горизонталь, на которой находится фигура (1...8)
  * @param theToFile   Вертикаль клетки, на которую выполняется ход (1=a, 8=h)
  * @param theToRank   Горизонталь клетки, на которую выполняется ход (1...8)
  * @return true, если ход допустим, и false, если недопустим
  */
  boolean isValidMove(int theFromFile, int theFromRank, int theToFile, int theToRank) {
      . . .
  }
...Показать Скрыть
8. Александр Орефков (orefkov) 15.05.13 12:19
Я было подумывал делать в таком виде:
Код
//** Описание процедуры
Процедура Некая(Парам1, //@ описание параметра
                Парам2, //@ описание параметра
                Знач Парам3) //@ описание параметра
Показать полностью

Но тоже как-то показалось не очень красиво. Потому пока и не делаю ничего, жду, может что-то вызреет.
9. Ярослав Волохов (YVolohov) 15.05.13 12:30
(8) Да, нужно держать каждый параметр в отдельной строке. А это уже потеря определенной свободы при разработке. Жаль, что в 1с нет блочных комментариев, тогда бы могло взлететь.
10. Сергей Карташев (Elisy) 15.05.13 13:05
(6) orefkov,
Действительно, необходимо продумать стандарт. Думал над этим. Мне нравится синтаксис XML-документации, как в Visual C++ и C#. Скорее адаптированный под русский синтаксис.
   /// <summary>
   /// Description for SomeMethod.</summary>
   /// <param name="s"> Parameter description for s goes here</param>
   /// <seealso cref="String">
   /// You can use the cref attribute on any tag to reference a type or member 
   /// and the compiler will check that the reference exists. </seealso>
   public void SomeMethod(string s)
   {
   }
...Показать Скрыть
11. VVV (V_V_V) 15.05.13 15:25
Сделай русские синонимы для своих дескрипторов. Не все из java выросли. Если бы я использовал, было бы влом набивать (и помнить значения) @name, @desc, @author, @var, @param, @return, плюс наверняка еще добавятся...
А так идея неплохая
12. Ярослав Волохов (YVolohov) 15.05.13 15:39
(11) Резонное замечание, сделаю.
13. SergeyFirst (SergeyFirst) 16.05.13 11:16
Неплохо было бы анализировать не отдельный файл, а "натравливать" обработку на каталог с выгруженными модулями из всей конфигурации и по результату строить целостную документацию по всей конфигурации.

Так же помимо анализа модулей неплохо бы в итоговой документации видеть описание объектов конфигурации с их реквизитами и структурой модулей, а так же с возможностью перехода по ссылками в зависимости от типа реквизита.

Вообще вариант с описанием в виде xml видится более перспективным и дающим большие возможности.
14. Ярослав Волохов (YVolohov) 16.05.13 11:57
(13) В следующих релизах по крайней мере часть этих пожеланий будет реализована. Что касается групповой обработки большого количества модулей (если нужно уже сейчас), то ее можно организовать используя две функции API:

ПолучитьСтруктуруМодуля() - сюда скармливаем текст модуля в виде строки и получаем разобранную структуру;
СоздатьОписаниеМодуляВФорматеMXL() - сюда передаем структуру модуля (возвращенную предыдущей функцией) и получаем табличный документ.
15. Misha ⁠ (Magister) 16.05.13 14:07
(0) Таки доделал :) Поздравляю!

По поводу дублирования параметров - в принципе, можно с помощью Снегопата автоматизировать поддержание списка параметров в актуальном виде, и сделать более удобный интерфейс для написания документации.
Если будет время - может быть возьмусь, задача интересная, хотя для меня и не приоритетная - я обычно в голове держу описание большинства используемых мной функций.
16. Валентин Бомбин (so-quest) 16.05.13 14:10
Топикстартеру - прикольно. особенно ценник улыбнул (хотя если сделана поддержка препроцессора и есть возможность расширять анотированные символы - тогда респект) И еще - забей болт (большой и толстый) на mxl - для этой задачи он не нужен. Надо XML по схеме GASTM - а там уже XSLT преобразованием делается все что надо.
17. Ярослав Волохов (YVolohov) 16.05.13 14:27
(15) Спасибо :)
Слабая документированность типовых меня всегда напрягала. Там сколько кода можно повторно использовать, но найти его настоящая проблема.

(16) Ну на огромные продажи я не очень то рассчитываю :) Хотя чем черт не шутит. В будущем может стать стандартом.
А про xml думал. Сохранять доку в какой-то промежуточный формат, из которого потом можно легко сформировать хоть веб-страницу, хоть документ word, хоть pdf без повторного парсинга исходников.
18. Валентин Бомбин (so-quest) 16.05.13 14:52
а что там думать? ast - дерево, xml - дерево - один в один сохраняется. Завтра тебе выложу преобразование кода в хмл.
19. Ярослав Волохов (YVolohov) 16.05.13 15:03
(18) Выкладывай, посмотрю. Сейчас в обработке есть возможность сохранять структуру документации во внутренне строчное представление 1с (ну ЗначениеВСтрокуВнутрь()), но она плохо читабельна для человека и нет гарантии, что 1с в один прекрасный момент не изменит формат и все файлы сразу станут не читабельны.
20. Модератор раздела Артур Аюханов (artbear) 16.05.13 15:56
(10) Для 1С++ в свое время мы делали подобный хмл-формат.
Народ даже использовал, было довольно удобно.
У нас из этих комментариев собирались als, ints, tls-файлы для 1С-Помощника и Телепата с Интеллисенсом.
21. Валентин Бомбин (so-quest) 17.05.13 14:07
бери пока отсюда https://github.com/wwall/GPTemplate когда пройдет модерацию - выложу тут инфостартовскую ссылку
В приложении - схема и результат разбора.
upd - инфостартовская ссылка http://infostart.ru/public/186724/
Прикрепленные файлы:
xsd_ParseResult.xml
ParseResult.xml
22. Ярослав Волохов (YVolohov) 17.05.13 15:48
23. artem666 Bogomaz (artem666) 19.05.13 11:45
Как это повлияет на 1С Совместимо ?
24. Валентин Бомбин (so-quest) 19.05.13 13:40
25. Ярослав Волохов (YVolohov) 19.05.13 19:34
(23) Думаю никак. Насколько я помню, 1С Совместимо не требует документировать API, только пользовательский интерфейс.
26. Алекс Ю (AlexO) 20.06.13 17:13
Вижу только еще одну тщетную попытку исправить окно в покосившемся доме с дырявыми стенами.
Считаю, что пока не сделают крепкие стены и не худую крышу - все остальные доработки будут лишь еще больше "дырявить" места их приложения (как новая заплата на старых штанах).
Да и всю немалую конфу перелопачивать за ради видеть объявления переменных, и при том в Предприятии - удоволствия мало.
27. Ярослав Волохов (YVolohov) 20.06.13 17:37
(26) Суть же не в том. Возьмем такую ситуацию: я нахожу в одном из модулей типовой конфигурации некую функцию, которая, как мне кажется, делает как-раз то, что мне нужно. Каким образом понять, что передавать ей на вход, что она возвращает и что она вызывает (если нужно перенести весь алгоритм в другую конфигурацию)?
Вариантов два - запустить ее на выполнение и посмотреть в отладчике, или разобрать код статически. Оба занимают определенное время и не очень приятны. Мне, например, намного комфортнее писать свой код, чем разбирать чужой. К тому в типовых есть функции, которые могут занимать по 50 страниц кода и больше. Разбор такого монстра это уже тяжелая и долгая работа.
Было бы очень здорово, если бы с функцией можно было работать как с черным ящиком. Передал на вход данные, получил на выходе результат. Что там происходит внутри - разработчика не должно интерсовать вообще. Вот для этого то и нужна документация.
В VS, Eclipse, IDEA и прочих продвинутых IDE достаточно вызвать автодополнение и выделить там нужную функцию. Программа сама найдет в документации описание этой функции, и оно практически моментально появится перед разработчиком.
В 1С же даже описание функции платформы нужно долго и нудно искать в синтаксис помощнике. Описаний же пользовательских функций вообще не предусмотрено как явления.
28. Сергей Марченко (MarSeN) 08.08.13 22:44
(8) orefkov,
а если в описании не дублировать вообще имена а указывать порядковый номер?
т.е.

//** Описание процедуры
//@р1 описание параметра
//@р2 описание параметра
//@р3 описание параметра
Процедура Некая(Парам1,Парам2,Знач Парам3)

задается именно порядок. тогда и следить не надо за расхождениями имен в описании и процедуре.
Тогда и ты в Снегопате по порядковому номеру сможешь подтянуть описание и автор скомпоновать корректное описание процедур, заменив p1 на Парам1
29. Александр Романько (romankoav) 01.02.16 17:47
Появились ли русские дискрипторы?
30. nicolas eliseev (nicxxx) 30.09.16 01:10
А в XML не научились сохранять?
Для написания сообщения необходимо авторизоваться
Прикрепить файл
Дополнительные параметры ответа