Дополнительное документирование модулей

1 17 марта 2021 16:13

Phoenix

TurboConf Скрипты

Тегами, подобными DoxyGen документируем модуль, получаем подсказку во время разработки.

Бывают случаи, когда нельзя сильно менять модуль, но можно добавить свои комментарии по тому или иному блоку/объекту.
Этот скрипт помогает получить Ваше дополнительное описание без переходов по модулю.
При документировании используются теги от DoxyGen, набор обрабатываемых тегов минимален, но достаточен.
Добавлен свой тег @alias.

Обрабатываемые теги:
@brief - Текстовое описание
@var - описание переменной
@fn - Описание метода
@param - описание параметра метода
@return - описание возврата метода
@alias - синоним, алиас

Правила документирования:
Описанием является комментарий в определенном формате
//<Пробел><ИмяТега><Пробел><ОписаниеТега>

Возможны многострочные текстовые описания.
Перенос текста осуществляется по шаблону: //<Пробел><Таб><Таб>Продолжение текста

Для тега @fn обязательно наличие тега @return.

Первая строка тега @brief используется является именем и используется для поиска. Таким образом, можно создавать несколько описаний для одного объекта, текста. В приведенном ниже примере, описание можно получить и для текста "Получить структуру модуля".
При выводе подсказки все описания объединяются.

Пример модуля:

// @brief Получить структуру модуля
// 		Продолжение краткого описания
// 		Продолжение краткого описания 2
// 		Продолжение краткого описания 3

// @fn МояФункция
// 		@brief Заменить исходный текст указанным значением
// 			Дополнительное описание метода
// 		@param ТекстДляОбработки Строка Перезаписывается значение переменной.
// 		@param ТекстЗамены Строка
// 		@return

Процедура МояФункция(ТекстДляОбработки, ТекстЗамены)
	
КонецПроцедуры

Процедура МояПроцедура1()
	// @var Строка ТекстВыхода 
	// @brief ТекстВыхода
	// 		Описание переменной "ТекстВыхода"
	// 		Еще описание переменной
	ТекстВыхода = "Получить структуру модуля";
	
	// @var Справочник.Контрагенты ВладелецК
	ВладелецК = Неопределено;
	
	// @alias Параметры = ПараметрыМетодов
	Параметры = ТекстВыхода;
КонецПроцедуры

Процедура СоздатьДокумент(ФайлИсточник, ФайлПриемник, ТолькоЭкспортные) Экспорт
	
	// Какие-то комментарии
	ТЗМетодов = Новый ТаблицаЗначений;
	ТЗМетодов.Колонки.Добавить("Имя");
	ТЗМетодов.Колонки.Добавить("Публичный");
	ТЗМетодов.Колонки.Добавить("Ссылка");
	
КонецПроцедуры

Как это работает:
Костыли.gif