Page 1 of 1

Документация прямо в коде.

Posted: Sun Jun 12, 2011 1:06 am
by XVilka
Всем известна проблема с документацией в колибри.
Однако современная тенденция - автогенерация документации (а-ля doxygen) из комментариев в коде. В том числе и для FASM

пример скрипта на Perl http://rudy.mif.pg.gda.pl/~bogdro/inne/

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

Re: Документация прямо в коде.

Posted: Sun Jun 12, 2011 1:12 am
by Mario
Из критики - комментариев мало и понятны они обычно только авторам.

Re: Документация прямо в коде.

Posted: Sun Jun 12, 2011 1:14 am
by XVilka
Потому их и надо стандартизировать.
Благо знание ассемблера не нужно для редактирования комментариев.
Справиться человек без скиллов программирования

Re: Документация прямо в коде.

Posted: Sun Sep 28, 2014 4:11 pm
by irkant
XVilka wrote:Потому их и надо стандартизировать.
Благо знание ассемблера не нужно для редактирования комментариев.
Справиться человек без скиллов программирования
И как, не разбираясь в коде, определить корректность и полноту комментария? :)
С документацией печаль полнейшая, тут согласен. Но писать ее в основном придется ручками, какую-то автоматизацию можно прикрутить только к будущему коду, формализовав процедуры разработки.

Re: Документация прямо в коде.

Posted: Tue Jun 29, 2021 3:58 pm
by Boppan
Кое кто мог заметить новую ссылку рядом с ссылкой на SVN: теперь у нас есть свое подобие доксигена. Генерируется скриптом asmxygen, уже поддерживает все конструкции, используемые в ядре, что я нашел: макросы, переменные, функции, декларации структур, в будущем планируется доксидокументирование констант.

Использовать Doxygen в ядре уже можно, пример документированной таким способом функции: https://builds.kolibrios.org/doxygen/ht ... 531e1fc75a

В случае появления вопросов или пожеланий по утилите, генерирующей доксиген, для нее создана отдельная тема.

Re: Документация прямо в коде.

Posted: Thu Jul 01, 2021 1:32 pm
by GerdtR
Это вау! Реально круто. Жаль, что когда я ковырял ядро, этой штуки не было.