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