Итак, надо определится с генератором документации. Я поразбирался с имеющимися: NDoc3, Sandcastle, Doxigen, Docu и сделал небольшой обзор.

NDoc3

http://sourceforge.net/projects/ndoc3/

Производит впечатление заброшенного продукта. Сайта нет, комиты очень редки. .Net 4.0 не поддерживается и такими темпами не будет. Посему был списан со счетов сразу.

Sandcastle

http://sandcastle.codeplex.com/

Большой комбайн от майкрософт, умеет все. Как генератор документации подходит. Причем с его помощью можно генерировать не только API, но и обычные статьи (у него собственный язык разметки MAML, то на чем сделан MSDN). Это радует, на нем можно сделать полный проект документации по языку. С генерацией chm, rtf и страниц для сайта. Для использования потребуется написать несколько плагинов для Nemerle (отображение методов в стиле nemerle, подсветку синтаксиса на регэкспах). Сгенерированую на нем доку по Nemerle, Nemerle.Macros и Nemerle.Compiler можно посмотреть здесь.

Минусы: крайне тяжел и медлителен, несколько раз падал без внятного сообщения о причинах. Хайлайтер на регэкспах расширить можно, но довольно сложно. Подозреваю, что плагин для языка тоже будет не прост.

Doxygen

http://www.stack.nl/~dimitri/doxygen/

Хороший и качественный продукт. Генерирует отличный html, chm и pdf. Документирует только API, причем по исходникам, без рефлекшена, что я считаю плюсом.

Минусы: расширяемость никакая. Нужна собственная сборка, со вшитым лексером. Либо скрипты приводящие исходники в сишный вид. Думаю такие подходы должны пойти в топку.

Docu

http://docu.jagregory.com/

Очень легковесный генератор API документации. Легко кастомизируется, я даже сделал форк генерирующий доку в синтаксисе nemerle. Результат для Nemerle и Nemerle.Macros можно посмотреть тут. Допилить его для поддержки макросов проще всего.

Минусы: не умеет ничего кроме API, документация генерируется в стиле RDoc (рубийный формат), что не очень юзабельно на мой взгляд. Не умеет chm.

Выводы

Надо либо писать плагины для сандкастла и переводить статьи из вики в MAML. Получится очень качественная цельная дока, но трудозатрат реально много.

Либо остановиться на доке по API, тогда docu будет достаточно, можно только шаблон изменить, что для человека знающего верстку будет несложно. Он очень прост и за счет этого кастомизируется влет.

В любом случае надо пройтись по исходникам и проставить xml каменты.

Здравствуйте, Ziaw, Вы писали:

Z>

Выводы

Z>Надо либо писать плагины для сандкастла и переводить статьи из вики в MAML. Получится очень качественная цельная дока, но трудозатрат реально много.

Z>Либо остановиться на доке по API, тогда docu будет достаточно, можно только шаблон изменить, что для человека знающего верстку будет несложно. Он очень прост и за счет этого кастомизируется влет.

Z>В любом случае надо пройтись по исходникам и проставить xml каменты.

Забыл написать о еще одной возможности. Сделать свой генератор на основе ndoc, он тоже умеет генерить полноценную документацию.

Nemerle для таких вещей подходит идеально, там как раз куча деревьев и раздолье для PM и функционального подхода. Тул выглядит очень востребованным .net сообществом, вполне себе real world app. Правда завистники опять будут утверждать, что все разработки крутятся вокруг компилятора

Здравствуйте, VladD2, Вы писали:

VD>Здравствуйте, Ziaw, Вы писали:

Z>> Сгенерированую на нем доку по Nemerle, Nemerle.Macros и Nemerle.Compiler можно посмотреть здесь.

VD>К chm-у нужно еще и chi класть. Иначе их невозможно посмотреть.

Никакого chi не нужно. Проблема в чем-то другом.

Здравствуйте, Ziaw, Вы писали:

Z>Здравствуйте, VladD2, Вы писали:

Z>>>Никакого chi не нужно. Проблема в чем-то другом.

VD>>А ты попробуй.

Z>Конечно же я попробовал, прежде чем написать. Поэтому пишу, что проблема в чем-то другом. Есть еще люди у которых она воспроизводится?

Влад, попробуй по правой кнопке "Свойства" => "Разблокировать".
Обычно в этом проблема

Здравствуйте, 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.

Здравствуйте, Ziaw, Вы писали:

Z> Сгенерированую на нем доку по Nemerle, Nemerle.Macros и Nemerle.Compiler можно посмотреть здесь.

К chm-у нужно еще и chi класть. Иначе их невозможно посмотреть.

Здравствуйте, Ziaw, Вы писали:


Отличный обзор!

Мне кажется, chm/rtf — анахронизм.
А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.

Здравствуйте, catbert, Вы писали:

C>Отличный обзор!

C>Мне кажется, chm/rtf — анахронизм.
C>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.

Если я правильно понимаю то docu делает доку [ каламбур ] по dll без xmldoc.
Или я не прав?

Здравствуйте, alvas, Вы писали:

C>>Отличный обзор!

C>>Мне кажется, chm/rtf — анахронизм.
C>>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.

A>Если я правильно понимаю то docu делает доку [ каламбур ] по dll без xmldoc.
A>Или я не прав?

Не прав Это было бы полным убожеством, генерить документацию без xmldoc. Я же дал ссылку на сгенеренную ей доку. http://ziaw.github.com/Nemerle.Utility/Pair.htm

Здравствуйте, Ziaw, Вы писали:

Z>Никакого chi не нужно. Проблема в чем-то другом.

А ты попробуй.

Здравствуйте, VladD2, Вы писали:

Z>>Никакого chi не нужно. Проблема в чем-то другом.

VD>А ты попробуй.

Конечно же я попробовал, прежде чем написать. Поэтому пишу, что проблема в чем-то другом. Есть еще люди у которых она воспроизводится?

Здравствуйте, catbert, Вы писали:

C>Отличный обзор!

C>Мне кажется, chm/rtf — анахронизм.
C>А мой вариант — документация по API из docu + выдержка из вики в качестве туториала/текстов.

Это надо в учебники по оверквотингу

You will always get what you always got
  If you always do  what you always did

Здравствуйте, catbert, Вы писали:

C>Мне кажется, chm/rtf — анахронизм.

Зато этот анахронизм не вызывет проблем на Линукс (RTF). Может и смотрелка chm-ов какая есть!

А что за проблема с тулзами "генерит только API"? А что ещё нужно-то?

Здравствуйте, Ziaw, Вы писали:

Z>Нужно вынести. Вообще для этого достаточно парсера. Идея генрить доки по сгенеренному коду (как делается сейчас) мне не нравится, документировать надо исходники, а не то, что по ним сгенерилось. Хотя для библиотек такой подход может быть не очень удобным.

Я думаю приоритетней сделать болванки для /// в интеграции + написание примеров.
Вот так я вытянул примеры из xmldoc для своей либы.

Хотя если посмотреть на

_N_operator_1414502915_2808Macro
_N_operator_660670116_2812Macro
_N_operator_707724294_2814Macro
_N_operator_775948391_2776Macro
_N_operator_781629578_2774Macro
_N_operator1214590000_2784Macro
_N_operator1220271919_2806Macro
_N_operator1617874545_2816Macro
_N_operator1974104882_2772Macro
_N_operator1979786069_2778Macro
_N_operator2021159060_2782Macro
_N_operator2073895137_2794Macro
_N_operator502129272_2798Macro
_N_operator502129275_2802Macro
_N_operator502129280_2788Macro
_N_operator502129282_2792Macro
_N_operator502129286_2786Macro
_N_operator502129287_2790Macro
_N_operator502129361_2800Macro
_N_operator502129395_2804Macro
_N_operator67864986_2613Macro
_N_operator905413823_2810Macro
_N_operator911095789_2796Macro
_N_operator931298021_2780Macro

то конечно вы правы

P.S. Примеры макросов из Nemerle.Core Namespace

Здравствуйте, alvas, Вы писали:

A>Влад, попробуй по правой кнопке "Свойства" => "Разблокировать".
A>Обычно в этом проблема

Ага. Попробовал разархивировать ТоталКомандером — файл открылся нормально. У нас те же проблемы были когда мы забывали выложить chi. Потому об этом и сказал.

Здравствуйте, matumba, Вы писали:

M>А что за проблема с тулзами "генерит только API"? А что ещё нужно-то?

А какой смысл в такой "документации"? Чем она будет отличаться от Object Browser в VS или Reflector-а? Там тоже можно посмотреть сигнатуры и ХМЛ-док-коменты в красивом виде.

Типа решение психологических проблем?

Здравствуйте, alvas, Вы писали:

A>Я думаю приоритетней сделать болванки для /// в интеграции + написание примеров.
A>Вот так я вытянул примеры из xmldoc для своей либы.

У нас некоммерческая организация. По сему есть правило, кто предлагает, тот и реализует.

Займись! Мы тебе поможем советами. Задача не сложная. Думаю ты с ней справишься.

Здравствуйте, catbert, Вы писали:

Извиняйте за оверквотинг, писал с телефона

Здравствуйте, VladD2, Вы писали:

VD>Здравствуйте, alvas, Вы писали:

A>>Я думаю приоритетней сделать болванки для /// в интеграции + написание примеров.
A>>Вот так я вытянул примеры из xmldoc для своей либы.

VD>У нас некоммерческая организация. По сему есть правило, кто предлагает, тот и реализует.

VD>Займись! Мы тебе поможем советами. Задача не сложная. Думаю ты с ней справишься.

Нужна помощь! Кто делал FileCodeModel для интеграции?
Проблема такая — FileCodeModel.CodeElementFromPoint ничего не возвращает для простого примера.

module Program
{
    
    Main() : void
    {
        WriteLine("Hi!");
        _ = ReadLine();
    }
}

Кто может помочь?

Здравствуйте, alvas, Вы писали:

VD>>Займись! Мы тебе поможем советами. Задача не сложная. Думаю ты с ней справишься.

A>Нужна помощь! Кто делал FileCodeModel для интеграции?

Кстати, можно узнать, что должна делать задача? Просто компилятор сам добавляет summary для таких тегов если оно отсутствует.
Можно просто написать

/// моя дока

все что можно добавить — описание параметров.

Здравствуйте, Ziaw, Вы писали:

Z>Здравствуйте, alvas, Вы писали:

VD>>>Займись! Мы тебе поможем советами. Задача не сложная. Думаю ты с ней справишься.

A>>Нужна помощь! Кто делал FileCodeModel для интеграции?

Z>Кстати, можно узнать, что должна делать задача? Просто компилятор сам добавляет summary для таких тегов если оно отсутствует.
Z>Можно просто написать

Z>

Z>/// моя дока
Z>

Z>все что можно добавить — описание параметров.

        /// <summary>
        /// 
        /// </summary>
        /// <param name="format"></param>
        /// <param name="data"></param>
        /// <param name="silentLevel"></param>
        /// <returns></returns>
        public static bool CheckSilent(IntPtr format, byte[] data, short silentLevel)

но лучше еще плюс

        /// <example>
        /// <code>
        /// </code>
        /// </example>