С вашей точки зрения на что должна быть похожа (или не похожа) строка комментария что бы по ней и документация легко генерилась, и читалось легко?
Вот я лично склоняюсь к мысли что javadoc вполне подходит.
Имхо, самым полезным было бы не изобретение собственного, а анализ существующей структуры документирования подпрограмм в 1С. Бывают же перед некоторыми функциями / процедурами их описания. Другое дело, что структура такого описания не имеет явной формализации.
Требовать и эффективности, и гибкости от одной и той же программы — все равно, что искать очаровательную и скромную жену... по-видимому, нам следует остановиться на чем-то одном из двух. Фредерик Брукс-младший
