Долго не мог понять в чем проблема, но только что разобрался и тороплюсь доложить вам. Заметил, что читая документацию в MSDN’е на душе становится как-то хорошо и спокойно, а когда читаю в doxygen’е, то как-то подташнивает.
Никто не будет спорить, что документация очень важна, особенно если нужно разбираться в новом большом проекте. И не в последнюю очередь важно качество документации, каким образом она составлена и подана читателю. Вещь непростая, измерить, кажется, трудно. Хотя можно было бы взять группу людей, дать им задачу найти перечень фактов в документации с разным дизайном, и измерить время считывания, поиска информации.
Так вот, если меня интересует какой-либо класс из библиотеки .NET, то в MSDN’е описание выглядит так:
Здесь четко видно: секция «конструкторы» — один метод, секция «методы» — пять. Плотность подачи информации равна шести единицам. Давайте посмотрим на документацию в дефолтовом стиле doxygen’а:
Секции всё также видны, но так легко считать отдельные методы уже не получается. Визуально толстые синие ссылки доминируют над декларациями методов, и отвлекают внимание. Более того, на одном экране мы видим описание только трёх методов. Значит условная плотность равна трём.
Обратите внимание, как doxygen заботливо тип «unsigned» сделал ссылкой. Если вы забудете, что такое unsigned, то вы всегда сможете пройти по ссылке и узнать.
Важная часть документации — это не только описание, но и примеры исходного кода. В MSDN’е мы видим исходники в таком оформлении:
Раз, два, три, четыре — и всё. Четыре цвета. Исходный код в doxygen’е выглядит так:
Здесь же мы видим такие классы подсветки: 1) директивы; 2) ссылки; 3) ключевые слова раз; 4) ключевые слова два; 5) комментарии; 6) встроенные типы; 7) идентификаторы, пунктуация. Итого семь разных цветов. Понятно, что подкраска — это дело вкуса, но если пользователь и так знает, что на любой идентификатор можно кликнуть и перейти в место определения, то зачем лишний раз выделять ссылки синим цветом?
Ну и на последок уменьшенная в пять раз collaboration diagram из doxygen’а. Реально кто-то будет ей пользоваться будучи в реальном размере (3600 на 1500 пикселей, смотреть оригинал)?
В комментариях приветствуются ссылки на мануалы и личный опыт ведения документации, настройки doxygen’а и прочее.
Сообщения
Во-первых, я что-то не уверен, что в MSDN документация генерилась автоматом прямо из кода.
ОтветитьУдалитьВо-вторых, в doxygen ты можешь настраивать стили так, как тебе удобно.
Но замечания вообще верные, согласен.
Давай различать две вещи: а) как оно генерировалось; и б) как оно выглядит. Очевидно, что в MSDN'е оно выглядит лучше. (Кстати, в 2008 и 2010 встроен XML-генератор документации. Поэтому MSDN может быть и сгенерирован.)
ОтветитьУдалитьИ второе: почему нельзя сразу сделать красиво, чтобы не мучить пользователей? Зачем нужно лезть, вникать во все эти стили и настройки, тратить время на настройку и перегенерацию, чтобы сделать нормальную документацию?
Зачем «давай различать»? Эти вещи взаимосвязаны хотя бы потому, что никакая утилита не сможет разделить код по каким-то логическим признакам так, как это может сделать человек.
ОтветитьУдалитьВпрочем, конкретно в приведённом тобой примере я не вижу причин не сделать красиво сразу, так что в принципе ты прав.
P.S. Генератор документации из xml появился вроде ещё в 2005 студии. Кстати, doxygen поддерживает этот формат тоже.
Что-то я перестал тебя понимать. Логические признаки - это метакомментарии. Всё, что нужно было сделать: это в левой колонке таблицы написать декларацию метода, а в правой колонке описание. Какой утилите это не сможет?
ОтветитьУдалитьМне кажется, что сравниваются немного разные вещи. MSDN - это всё-таки не утилита, для создания документации, коим является doxygen. Думаю, что MSDN тоже создается каким-нить MC аналогом doxygen'a. В котором тоже заботливые люди настраивали стили, шрифты, цвета.
ОтветитьУдалитьНикогда не пользовался doxygen, но насколько слышал, там есть возможность кастомизиворать многое.
Ребяты, ну вы, это...
ОтветитьУдалитьНе сравниваются утилиты по генерации. Сравнивается подача. И то, и другое является онлайн-документацией к библиотекам классов. И там, и там одинаковые технологии HTML, CSS, JavaScript. Значит цели и возможности у них одинаковые. Дизайн MSDN'а на моей памяти менялся раза три точно. Первый раз я столкнулся с ним в далёком 2001 году, но он уже тогда был красивее, чем дефолтный стиль доксигена.
Да, ты прав что дефолтный стиль доксигена просто слишком тошнотворен, на фоне MSDN.
ОтветитьУдалитьПросто хотел заметить, что усилия разработчиков доксигена были потрачены на создание открытой утилиты, которой будут пользоваться для создания документации для проектом на различных языках.
И тем не менее, доксигеном можно сгенерировать документацию с приличным видом.
доксигеном можно сгенерировать документацию с приличным видом.
ОтветитьУдалитьСкриншоты и ссылки на конфиги в студию!
Здесь пример приличного видом. Конфиги не знаю, потому что, как писал ранее, никогда не пользовался доксигеном.
ОтветитьУдалитьЭтот пример более-менее. Спасибо!
ОтветитьУдалитьКстати по поводу примера. Я не уверен, но по-моему пример в последней ссылке как раз и есть дефолтный стиль доксигена или по крайней мере очень к нему близкий.
ОтветитьУдалитьВообще, ты молодец, что начал эту тему. На досуге как-то может займусь созданием таблицы стилей a la MSDN для доксигена.
GooRoo, это будет полезный труд. Держи нас в курсе.
ОтветитьУдалить