По поводу внедрения документации в текст программы всем смотреть JavaDOC и из нёё вытекающие (PHPDOC, Summary в .NET).

Смысл сводится к тому, что есть некие "тэги" между которыми идёт текст документации, а затем специальная софтина обрабатывает текст программы на предмет генерации доки.

например:

; /// [DOC]
; /// PRINTCHAR - выводит в поток символ
; /// из регистра A
PRINTCHAR
RST #10
RET

почти каждый спековский ассемблер поддерживает экспорт в текст. а текст обработать- нефиг делать.

если грамотно настроить генерилку, то можно не ограничиваться ассемблером

// /// [DOC]
// /// example
void example(void) {}

/*
/// [DOC]
/// example2
*/
void example2(void) {}

1) не надо изголяться с DOC_MODE
2) документация не оторвана от текста программы (т.е. можно написать аффигительную генерилку, которая кроме выдирания доки, будет ещё раскрашивать и форматировать текст программы