...элементарное разделение на спецификацию и реализацию модуля. Что весьма печально.
Чет я не очень понял.
А с какой целью?
С целью последующей вменяемой работы с исходниками. Когда я вижу тонну кода мне совсем не интересно лазить по потрохам реализаций и пытаться выцепить что же оно там экспортирует и зачем. Мне интересно пройтись по спецификациям модулей писаным ЧЕЛОВЕКОМ с человеческими же коментариями для вводимых сущностей.
Например по исходникам библиотеки писаной на Аде (благодаря наличиям спецификаций) я разбираюсь много быстрее (то есть понимаю какое место либы мне интересно, и как с этим работать) чем скажем в библиотеках на java. Документация в виде сгенерированных html'ей обычно есть и для того и для другого (причем для явы оно бывает чаще и подробней). Плюс адские исходники я смотрю обычно в каком-нибудь shell+cat|less/mc/far, а жабные - в IDE (eclipse/netbeans), которые таки генерируют нечто вроде спецификации и позволяют интерактивно по ней лазить. Но Адские спеки на модули все равно удобней и читаемей просто потому, что их пишет человек, а не генерит аццкая железка из реализации.
Более того, если есть по человечески писаные хедеры для С++ кода (то есть это когда там не аццкого фарша из #ifdef'ов) то по ним я тоже разбираюсь в сути того что там делает программа и какие её места мне нужны и важны быстрее, чем скажем в программе на Обероне. Ну и уж в коллекции модулей писаных на Модуле2/3 разбираться на порядок проще чем в обероновской аналогичной коллекции.