Производит впечатление заброшенного продукта. Сайта нет, комиты очень редки. .Net 4.0 не поддерживается и такими темпами не будет. Посему был списан со счетов сразу.
Большой комбайн от майкрософт, умеет все. Как генератор документации подходит. Причем с его помощью можно генерировать не только API, но и обычные статьи (у него собственный язык разметки MAML, то на чем сделан MSDN). Это радует, на нем можно сделать полный проект документации по языку. С генерацией chm, rtf и страниц для сайта. Для использования потребуется написать несколько плагинов для Nemerle (отображение методов в стиле nemerle, подсветку синтаксиса на регэкспах). Сгенерированую на нем доку по Nemerle, Nemerle.Macros и Nemerle.Compiler можно посмотреть здесь.
Минусы: крайне тяжел и медлителен, несколько раз падал без внятного сообщения о причинах. Хайлайтер на регэкспах расширить можно, но довольно сложно. Подозреваю, что плагин для языка тоже будет не прост.
Хороший и качественный продукт. Генерирует отличный html, chm и pdf. Документирует только API, причем по исходникам, без рефлекшена, что я считаю плюсом.
Минусы: расширяемость никакая. Нужна собственная сборка, со вшитым лексером. Либо скрипты приводящие исходники в сишный вид. Думаю такие подходы должны пойти в топку.
Очень легковесный генератор API документации. Легко кастомизируется, я даже сделал форк генерирующий доку в синтаксисе nemerle. Результат для Nemerle и Nemerle.Macros можно посмотреть тут. Допилить его для поддержки макросов проще всего.
Минусы: не умеет ничего кроме API, документация генерируется в стиле RDoc (рубийный формат), что не очень юзабельно на мой взгляд. Не умеет chm.
Выводы
Надо либо писать плагины для сандкастла и переводить статьи из вики в MAML. Получится очень качественная цельная дока, но трудозатрат реально много.
Либо остановиться на доке по API, тогда docu будет достаточно, можно только шаблон изменить, что для человека знающего верстку будет несложно. Он очень прост и за счет этого кастомизируется влет.
В любом случае надо пройтись по исходникам и проставить xml каменты.
Z>Надо либо писать плагины для сандкастла и переводить статьи из вики в MAML. Получится очень качественная цельная дока, но трудозатрат реально много.
Z>Либо остановиться на доке по API, тогда docu будет достаточно, можно только шаблон изменить, что для человека знающего верстку будет несложно. Он очень прост и за счет этого кастомизируется влет.
Z>В любом случае надо пройтись по исходникам и проставить xml каменты.
Забыл написать о еще одной возможности. Сделать свой генератор на основе ndoc, он тоже умеет генерить полноценную документацию.
Nemerle для таких вещей подходит идеально, там как раз куча деревьев и раздолье для PM и функционального подхода. Тул выглядит очень востребованным .net сообществом, вполне себе real world app. Правда завистники опять будут утверждать, что все разработки крутятся вокруг компилятора
Здравствуйте, Ziaw, Вы писали:
Z>Итак, надо определится с генератором документации. Я поразбирался с имеющимися: NDoc3, Sandcastle, Doxigen, Docu и сделал небольшой обзор.
хотелось бы сразу обсудить такую фишку:
как генерировать каменты из макросов, например для макроса NotNull и прочих assertions?
честно говоря не знаю как создаётся xmlDoc сейчас
в N2 мне видится так:
иметь дополнительные элементы в АСТ специально для доков.
для их генерации активизируется отдельный макрос — наверное лучше вынести эту логику из компилера
этот макрос проверяет флаг в параметрах компилера и отключается по необходимости
любой другой макрос также может это делать и изменяет элементы-коментарии в АСТ программы по необходимости
при генерации кода компилятор создаёт XML...
таким образом цепочка такая:
исходник->макрос->компилятор->xml->????->дока в каком-то формате
т.е. нужен инструмент, который работает именно с xml..
doxygen наверное не очень подойдёт...
Здравствуйте, para, Вы писали:
Z>>Итак, надо определится с генератором документации. Я поразбирался с имеющимися: NDoc3, Sandcastle, Doxigen, Docu и сделал небольшой обзор.
P>хотелось бы сразу обсудить такую фишку: P>как генерировать каменты из макросов, например для макроса NotNull и прочих assertions?
Надо допилить компилятор, чтобы он выдавал в xml doc макросы в нормальном виде. В виде классов, как сделано сейчас (и как они лежат в сборке) бесчеловечно.
P>для их генерации активизируется отдельный макрос — наверное лучше вынести эту логику из компилера
Нужно вынести. Вообще для этого достаточно парсера. Идея генрить доки по сгенеренному коду (как делается сейчас) мне не нравится, документировать надо исходники, а не то, что по ним сгенерилось. Хотя для библиотек такой подход может быть не очень удобным.
P>т.е. нужен инструмент, который работает именно с xml..
Да, я в итоге оставил инструменты которые работают именно с xml.
Здравствуйте, catbert, Вы писали:
C>Отличный обзор!
C>Мне кажется, chm/rtf — анахронизм. C>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.
Если я правильно понимаю то docu делает доку [ каламбур ] по dll без xmldoc.
Или я не прав?
Здравствуйте, alvas, Вы писали:
C>>Отличный обзор!
C>>Мне кажется, chm/rtf — анахронизм. C>>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.
A>Если я правильно понимаю то docu делает доку [ каламбур ] по dll без xmldoc. A>Или я не прав?
Здравствуйте, VladD2, Вы писали:
VD>Здравствуйте, Ziaw, Вы писали:
Z>> Сгенерированую на нем доку по Nemerle, Nemerle.Macros и Nemerle.Compiler можно посмотреть здесь.
VD>К chm-у нужно еще и chi класть. Иначе их невозможно посмотреть.
Здравствуйте, Ziaw, Вы писали:
Z>Здравствуйте, VladD2, Вы писали:
Z>>>Никакого chi не нужно. Проблема в чем-то другом.
VD>>А ты попробуй.
Z>Конечно же я попробовал, прежде чем написать. Поэтому пишу, что проблема в чем-то другом. Есть еще люди у которых она воспроизводится?
Влад, попробуй по правой кнопке "Свойства" => "Разблокировать".
Обычно в этом проблема
Здравствуйте, catbert, Вы писали:
C>Отличный обзор!
C>Мне кажется, chm/rtf — анахронизм. C>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.
Здравствуйте, Ziaw, Вы писали:
Z>Нужно вынести. Вообще для этого достаточно парсера. Идея генрить доки по сгенеренному коду (как делается сейчас) мне не нравится, документировать надо исходники, а не то, что по ним сгенерилось. Хотя для библиотек такой подход может быть не очень удобным.
Я думаю приоритетней сделать болванки для /// в интеграции + написание примеров. Вот так я вытянул примеры из xmldoc для своей либы.
Здравствуйте, alvas, Вы писали:
A>Влад, попробуй по правой кнопке "Свойства" => "Разблокировать". A>Обычно в этом проблема
Ага. Попробовал разархивировать ТоталКомандером — файл открылся нормально. У нас те же проблемы были когда мы забывали выложить chi. Потому об этом и сказал.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, matumba, Вы писали:
M>А что за проблема с тулзами "генерит только API"? А что ещё нужно-то?
А какой смысл в такой "документации"? Чем она будет отличаться от Object Browser в VS или Reflector-а? Там тоже можно посмотреть сигнатуры и ХМЛ-док-коменты в красивом виде.
Типа решение психологических проблем?
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
Здравствуйте, alvas, Вы писали:
A>Я думаю приоритетней сделать болванки для /// в интеграции + написание примеров. A>Вот так я вытянул примеры из xmldoc для своей либы.
У нас некоммерческая организация. По сему есть правило, кто предлагает, тот и реализует.
Займись! Мы тебе поможем советами. Задача не сложная. Думаю ты с ней справишься.
Есть логика намерений и логика обстоятельств, последняя всегда сильнее.
] по dll без xmldoc. 
