Долго не мог понять в чем проблема, но только что разобрался и тороплюсь доложить вам. Заметил, что читая документацию в MSDN’е на душе становится как-то хорошо и спокойно, а когда читаю в doxygen’е, то как-то подташнивает.
Никто не будет спорить, что документация очень важна, особенно если нужно разбираться в новом большом проекте. И не в последнюю очередь важно качество документации, каким образом она составлена и подана читателю. Вещь непростая, измерить, кажется, трудно. Хотя можно было бы взять группу людей, дать им задачу найти перечень фактов в документации с разным дизайном, и измерить время считывания, поиска информации.
Так вот, если меня интересует какой-либо класс из библиотеки .NET, то в MSDN’е описание выглядит так:
Здесь четко видно: секция «конструкторы» — один метод, секция «методы» — пять. Плотность подачи информации равна шести единицам. Давайте посмотрим на документацию в дефолтовом стиле doxygen’а:
Секции всё также видны, но так легко считать отдельные методы уже не получается. Визуально толстые синие ссылки доминируют над декларациями методов, и отвлекают внимание. Более того, на одном экране мы видим описание только трёх методов. Значит условная плотность равна трём.
Обратите внимание, как doxygen заботливо тип «unsigned» сделал ссылкой. Если вы забудете, что такое unsigned, то вы всегда сможете пройти по ссылке и узнать.
Важная часть документации — это не только описание, но и примеры исходного кода. В MSDN’е мы видим исходники в таком оформлении:
Раз, два, три, четыре — и всё. Четыре цвета. Исходный код в doxygen’е выглядит так:
Здесь же мы видим такие классы подсветки: 1) директивы; 2) ссылки; 3) ключевые слова раз; 4) ключевые слова два; 5) комментарии; 6) встроенные типы; 7) идентификаторы, пунктуация. Итого семь разных цветов. Понятно, что подкраска — это дело вкуса, но если пользователь и так знает, что на любой идентификатор можно кликнуть и перейти в место определения, то зачем лишний раз выделять ссылки синим цветом?
Ну и на последок уменьшенная в пять раз collaboration diagram из doxygen’а. Реально кто-то будет ей пользоваться будучи в реальном размере (3600 на 1500 пикселей, смотреть оригинал)?
В комментариях приветствуются ссылки на мануалы и личный опыт ведения документации, настройки doxygen’а и прочее.
Сообщения
