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

Со всем сказанным согласен кроме:

Z>Все генераторы док для .net которые я смотрел, либо устарели либо работают через рефлекшн либо все вместе. Между тем, у немерле есть особенности, которые делают сгенеренный IL далеким от того, что требуется документировать. Поэтому единственный рабочий способ это парсить исходники.

На самом деле давным давно документация генерировалась чем-то вроде Сендкасла. И генерировалась она не так уж плохо.

Единственный вопрос который имеется — это документация для макросов. С ней проблема, так с одной стороны макросы нестандартная сущность и документацию для них просто некуда положить, а с другой ее попросту нет.

Так что по уму сначала нужно было бы решить эту проблему в компиляторе. Можно засовывать док-коменты в некий атрибут или так же как стандартные в хмл-файл, но при этом нужно разобраться с форматом.

В любом случае хорошо бы иметь хинты в среде разработки. Их с исходников точно не сделать, если макрос пришел в виде библиотеки.

Вся остальная информация о макросах есть в самих макросах. Там и синтаксис описывается и все остальное:

  /** Interface, which will be implemented by class encapsulating macro
      function. It will allow dynamic execution of macro by compiler
      itself
   */
  public interface IMacro
  {
    GetName () : string;
    GetNamespace () : string;  
    Run (ctx : Typer, args : list [SyntaxElement]) : PExpr;
    CallTransform (_ : list [PExpr]) : list [SyntaxElement];
    SyntaxExtension () : GrammarElement * (list [SyntaxElement] -> list [SyntaxElement]);
    IsTailRecursionTransparent : bool { get; }
    IsInherited : bool { get; }
    Keywords : list [string] { get; }
    Usage : MacroUsageAttribute { get; }
    Location : Location { get; }
  }

Создать не хитрую программу которая бы вынимала список макросов и формирует по нему ХТМЛ задача на один вечер.

Все что нам нужно — это добавить к этому интерфейсу информацию из док.коментов.

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

Z>>Все генераторы док для .net которые я смотрел, либо устарели либо работают через рефлекшн либо все вместе. Между тем, у немерле есть особенности, которые делают сгенеренный IL далеким от того, что требуется документировать. Поэтому единственный рабочий способ это парсить исходники.

VD>На самом деле давным давно документация генерировалась чем-то вроде Сендкасла. И генерировалась она не так уж плохо.

Не так уж плохо там где не особо применяется метапрограммирование.

class A
{
   /// <summary>
   ///  i member documentation
   /// </summary>
   [Accessor] i : int = 42;
}

Можно и других примеров в придумать.

Это конечно не так уж критично, по большому счету.

VD>Единственный вопрос который имеется — это документация для макросов. С ней проблема, так с одной стороны макросы нестандартная сущность и документацию для них просто некуда положить, а с другой ее попросту нет.

VD>Так что по уму сначала нужно было бы решить эту проблему в компиляторе. Можно засовывать док-коменты в некий атрибут или так же как стандартные в хмл-файл, но при этом нужно разобраться с форматом.

+1. Это и в IDE поможет и макрос Accessor может перенести доку в свойство. Только атрибут это плохая идея.

VD>В любом случае хорошо бы иметь хинты в среде разработки. Их с исходников точно не сделать, если макрос пришел в виде библиотеки.

Из исходников надо генерить xml к dll, как делает компилятор C#, только вот все генераторы (типа sandcastle) кроме xml берут сборку и тупо выдирают все классы и все публичные методы рефлектором. По ним генерят доку, приджойнивая слева xml, а в генерируемом коде, кмк, есть сущности которые не хотелось бы туда помещать. Например анонимные типы.

Но есть еще один класс генераторов док, самый известный — doxygen, он курочит исходники (или то, что ты ему дашь в качестве исходников). Он вообще настраивается по самое не балуй, с ним можно попробовать поиграться.

VD>Вся остальная информация о макросах есть в самих макросах. Там и синтаксис описывается и все остальное:
VD>Создать не хитрую программу которая бы вынимала список макросов и формирует по нему ХТМЛ задача на один вечер.

Я в курсе.

VD>Все что нам нужно — это добавить к этому интерфейсу информацию из док.коментов.

Не только к этому.