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

Kernel architecture questions
Post Reply
User avatar
XVilka
Posts: 796
Joined: Tue Aug 25, 2009 4:45 pm

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

Post by XVilka »

Всем известна проблема с документацией в колибри.
Однако современная тенденция - автогенерация документации (а-ля doxygen) из комментариев в коде. В том числе и для FASM

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

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

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

Post by Mario »

Из критики - комментариев мало и понятны они обычно только авторам.
User avatar
XVilka
Posts: 796
Joined: Tue Aug 25, 2009 4:45 pm

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

Post by XVilka »

Потому их и надо стандартизировать.
Благо знание ассемблера не нужно для редактирования комментариев.
Справиться человек без скиллов программирования
irkant
Posts: 34
Joined: Wed Sep 24, 2014 5:47 pm

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

Post by irkant »

XVilka wrote:Потому их и надо стандартизировать.
Благо знание ассемблера не нужно для редактирования комментариев.
Справиться человек без скиллов программирования
И как, не разбираясь в коде, определить корректность и полноту комментария? :)
С документацией печаль полнейшая, тут согласен. Но писать ее в основном придется ручками, какую-то автоматизацию можно прикрутить только к будущему коду, формализовав процедуры разработки.
User avatar
Boppan
Posts: 63
Joined: Mon Aug 26, 2019 10:14 pm

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

Post by Boppan »

Кое кто мог заметить новую ссылку рядом с ссылкой на SVN: теперь у нас есть свое подобие доксигена. Генерируется скриптом asmxygen, уже поддерживает все конструкции, используемые в ядре, что я нашел: макросы, переменные, функции, декларации структур, в будущем планируется доксидокументирование констант.

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

В случае появления вопросов или пожеланий по утилите, генерирующей доксиген, для нее создана отдельная тема.
User avatar
GerdtR
Posts: 471
Joined: Mon Nov 19, 2012 5:22 pm

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

Post by GerdtR »

Это вау! Реально круто. Жаль, что когда я ковырял ядро, этой штуки не было.
Чем больше сыра, тем больше в нём дыр. Чем больше дыр, тем меньше в нём собственно сыра. Значит, чем больше сыра, тем меньше сыра!
Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest