gifts2017

Документирование 1С через комментарии

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

Для языков программирования Java, C++, C# и т.д. Созданы системы строящие документацию, через комментарии. А можно ли такое же в 1С?

Можно. Для этого потребуется:

  1. Установить ант
  2. Настроить ант
  3. Запустить ант
  4. Написать комментарии в коде

1. Что же такое ант?

Apache Ant (англ.ant — муравей и акроним — «Another Neat Tool») — утилита для автоматизации процесса сборки программного продукта. Является платформонезависимым аналогом утилиты make (в качестве «Makefile» применяется «build.xml»).

(с) Википедия

Скачать эту замечательную утилиту можно по адресу: http://ant.apache.org/bindownload.cgi.

 

К данной замечательной утилите потребуется два плагина. Первый это плагин http://ant-doxygen.blogspot.ru/, а второй - это плагин к анту, написаный мной и прекрепленный к данной статье.

Второй плагин ни делает ничего, кроме выгрузки модулей 1С и преобразования их в код на подобии java.

 

2. Как настроить ант?

К этой статье приложен файл: "build.xml", в нем надо заменить пути к файлам и значения, на ваши. Скачать и подправить файл настройки doxigen (так же приложен к данной статье).

3. Как запустить ант?

Запустить cmd.exe или PowerShell и перейти в каталог с файлом build.xml и запустить ant all.

4. Комментарии

Комментарии нужно оформить в стиле javadoc или doxigen, но есть маленькая специфика. Что бы ваша документация ложилаь по простанствам имен(пакетам) я добавил от себя следующие правила:

Если модуль начинается с комментария:

// $subsystem=[имя]

// [Какое-то описание]

// $

То это этот модуль попадет в [имя].ОбщийМодуль.ИмяОбщегоМодуля.

Если же такого комментария не будет, то он попадет в ОбщийМодуль.ИмяОбщегоМодуля.

5. Итог

Вуаля документация у вас готова.

 

P.S. Прошу прощенья, если описание не внятно. Но описание я пишу почти через год после написания программы. Может чего и забыл.

 

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

Наименование Файл Версия Размер Кол. Скачив.
Ант задача конвертирующая 1С тексты в ал-я java
.jar 8,02Kb
08.04.13
8
.jar 8,02Kb 8 Скачать
Пример конфигурационного файла doxygen
.dox 76,91Kb
08.04.13
8
.dox 76,91Kb 8 Скачать
Настройки анта
.xml 1,94Kb
08.04.13
8
.xml 1,94Kb 8 Скачать

См. также

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

Комментарии

1. script Мальчинко (script) 16.01.14 23:17
Ничего не понял вообще. Понятно только что документация, но какая и для чего и как настроить что бы заработало и что должно получится. Все равно что посадить пользователя, который работал на 7.7., перед УПП и сказать: Вот...
2. Василий Казьмин (awk) 17.01.14 00:47
(1) script,
Понятно только что документация, но какая и для чего

Ну, вот такая как на скриншете. Для того кому надо.
как настроить что бы заработало

Ну если вкурсе про ант, и doxigen - то подправить конфиги, а если нет - читать документаци по ант и доксигену.
что должно получится
А что бы вы хотели?
Все равно что посадить пользователя, который работал на 7.7., перед УПП и сказать: Вот.
В точку. Современные системы проектировани по сравнению с конфигуратором, как самолет и самокат. Токо что слова одинаковые "само".

Ну это юмор. Надеюсь я им не обидел, а заставил улыбнутся.


А серьезно можно по порядку? Что непонятно? Где найти документацию по установке? Или как форматировать комментарии в доксиген стиле? Я попробую ответить на конкретные вопросы.

3. Василий Казьмин (awk) 17.01.14 01:48
(1) script, Наверное, вам больше подойдет http://infostart.ru/public/88910/. Примерно то же самое, но используется только Power Shell.
4. Сергей Ожерельев (Поручик) 19.01.14 02:02
Для рядового одноэсника страница из разряда - долго читал, много думал.
5. Василий Казьмин (awk) 19.01.14 02:15
(4) Поручик, Для рядового одинесника (да простят меня на сайте - сам такой) много читал и думал - не свойственно. На все мои попытки что-то новое привить мои коллеги обычно отвечают - "Зачем и так деньги платят. Развиваться надо когда делать нечего."

Данную статью я опубликовал только из-за Артур Аюханов, который плюсанул за нее когда она была в черновом варианте, без описания совсем. Думал отделуюсь коротким хау-ту, ан нет придется писать, что такое ант, что такое доксиген.
6. Артур Аюханов (artbear) 21.01.14 19:15
(5) awk, Рад, что мой плюсик сработал :)
ЗЫ Исправь, пожалуйста, мое ФИО на "Артур Аюханов"
7. Василий Казьмин (awk) 21.01.14 19:19
(6) artbear, Прости, не со зла... Стыдно....
8. Валентин Бомбин (so-quest) 22.01.14 06:22
Зеркало есть для разработки? А то этих маней нет (и не будет видимо никогда :) )
9. Артем Артеменко (dock) 22.01.14 07:49
Вещь хорошая, жаль что мне пока не нужная :)
Автору почет и уважение.
10. Василий Казьмин (awk) 22.01.14 10:18
(8) so-quest, Да вроде на ассамблее было..
11. Антон Рощин (wolfsoft) 22.01.14 15:37
В 1С надо ссылку отправить, может хоть тогда у них документация начнёт соответствовать коду...
12. Василий Казьмин (awk) 22.01.14 15:52
(11) wolfsoft, А мы где? Территория инфостарт на половину принадлежит 1С.
13. Роман Ложкин (webester) 23.01.14 09:56
Необходимость в документировании, возникает при написании подсистем и работе в команде, я работаю уже много лет соло, да и подсистем не писал никогда. Но плюсану вдруг понадобится :)
14. Василий Казьмин (awk) 23.01.14 10:05
(13) webester, :))) Необходимость документирования обычно возникает гораздо позже написания (не важно в команде или в подсистеме). Правда возникает не в ста процентов случаев. Вот и получается - когда пишем, то ориентируемся на случай: "Авось не понадобится", а когда переписываем, то материмся на: "Суцко. Таки понадобилось".
15. Maxim Kolkin (the1) 23.01.14 17:23
(13) Ага, тоже плюсанул "на потом почитать" =)
16. rasswet (rasswet) 24.01.14 10:25
к сожалению ничего не понял.
17. Роман Ложкин (webester) 26.01.14 06:01
(16) значит вам это не нужно :)
smit1c; SirYozha; +2 Ответить
18. Евгений Сосна (pumbaE) 10.03.14 18:52
Стандартные комментарии 1С, преобразовывает в формат doxygen?
// Устанавливает статус для объекта документа
//
// Параметры:
//	НовыйСтатус - Строка - Имя статуса, который будет установлен у заказов
//	ДополнительныеПараметры - Структура - Структура дополнительных параметров установки статуса
//
// Возвращаемое значение:
//	Булево - Истина, в случае успешной установки нового статуса
//
Функция УстановитьСтатус(НовыйСтатус, ДополнительныеПараметры) Экспорт
...Показать Скрыть

В
// Устанавливает статус для объекта документа
//
// @param НовыйСтатус - Строка - Имя статуса, который будет установлен у заказов
// @param ДополнительныеПараметры {Структура} - Структура дополнительных параметров установки статуса
//
Функция УстановитьСтатус(НовыйСтатус, ДополнительныеПараметры) Экспорт
...Показать Скрыть


?
19. Василий Казьмин (awk) 11.03.14 10:31
20. nicolas eliseev (nicxxx) 30.09.16 15:20
а можно дополнить руководство разделом по настройке ANT ? а то сходу не понятно нифига:) да и времени на его подробное изучение нет :(
21. nicolas eliseev (nicxxx) 06.10.16 18:07
Не работает алгоритм:( Почему-то не конвертируются файлы выгрузки из 1С в файлы java, вот этот пункт из описания: "Второй плагин ни делает ничего, кроме выгрузки модулей 1С и преобразования их в код на подобии java."
Для написания сообщения необходимо авторизоваться
Прикрепить файл
Дополнительные параметры ответа