Расширение документации по классам и живых шаблонов

Я играю с документацией по коду и живыми шаблонами и совершенно не понимаю.

Я прочитал статью доктора Боба о создании документации и вики-статьи о живых шаблонах, но У меня есть одна проблема с описанием класса.

По описанию класса я понимаю поведение IDE, когда я навожу курсор мыши на объявление класса.

Например, у меня есть такой класс с его описанием:

type
  {$REGION 'TMyClass'}
    /// <summary>
    /// Summary works
    /// </summary>
    /// <remarks>
    /// Remarks works
    /// </remarks>
    /// <exception cref="www.some.link">This works</exception>
    /// <list type="bullet">
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// <item>
    /// <description>description does not work</description>
    /// </item>
    /// </list>
    /// <permission cref="www.some.link">This works</permission>
    /// <example>
    /// <code>
    /// Code example does not work
    /// </code>
    /// </example>
  {$ENDREGION}
  TMyClass = class
  private
    a, b, c: Integer;
  public
  end;

И позже в коде у меня есть такое объявление:

var
  MyObject: TMyClass;

Когда я навожу курсор мыши на тип класса, у меня есть такое описание:

Описание класса

Как вы видите, не все теги html были обработаны движком IDE. Я действительно хотел бы знать, как отображать дополнительные теги, особенно тег с примером кода. Является ли это возможным?

Я использую Delphi 2009 Proffesional.


person Wodzu    schedule 25.09.2011    source источник


Ответы (2)


Поддерживается только ограниченный набор тегов. Лучшая документация по этому вопросу, которую я знаю, — это Delphi Documentation Guidelines (в конце "Оглавления" есть ссылка на PDF).

person ain    schedule 25.09.2011
comment
Я не считаю это лучшей документацией по этому вопросу! Это документация по тегам, поддерживаемым коммерческим сторонним инструментом DevJet. Это не документация того, что поддерживает IDE. IDE на самом деле довольно хорошо документирует теги, поддерживаемые IDE, в интерактивной справке (и в docwiki). - person Rudy Velthuis; 26.09.2011
comment
Возможно, официальная документация была улучшена с тех пор, как я в последний раз изучал эту тему ... в то время, когда я изучал ее, предоставленная мной ссылка была лучшей (и только IIRC) документацией. - person ain; 26.09.2011
comment
Да, документ Devjet перечисляет больше тегов, чем поддерживается IDE, но сама документация намного лучше, чем официальная документация, которую вы разместили - в ней есть примеры и описания тегов, в то время как в docwiki просто есть список тегов... - person ain; 27.09.2011
comment
Спасибо. Я принимаю этот ответ, потому что ссылка на документацию, которую вы дали, более полезна, чем ссылка на вики. Wiki не говорит, как использовать теги ‹c› и ‹code› — я понятия не имел, что они должны содержаться в других тегах для правильной работы. - person Wodzu; 27.09.2011

Теги, которые поддерживает Help Insight, описаны в интерактивной справке и в документальной вики Delphi. Они представляют собой подмножество тегов, поддерживаемых тегами справки C#. Никакие другие теги, кроме перечисленных на сайте Embarcadero, похоже, не поддерживаются (я их пробовал). Единственные другие вещи, которые работают (и требуются), это "", "" и "".

Обновлять

Кажется, есть некоторые продукты, которые позволяют вам использовать полный синтаксис, например. описано в Руководстве по документации Delphi, на которое ссылается @ain. Но для этого вам нужно купить коммерческий продукт, например Documentation Insight от DevJet, который не следует путать с Help Insight, поддерживаемым IDE, начиная с Delphi 2006. .

Как вы узнали, и я тоже, только подмножество, описанное в доквики Delphi поддерживается голой IDE без коммерческих продуктов. Существует также документация, поддерживаемая интерфейсом моделирования, но она снова отличается. В обычной IDE вы можете использовать только те теги, которые мы с вами уже нашли.

person Rudy Velthuis    schedule 25.09.2011
comment
Привет, Руди. На самом деле теги XMLDoc — это просто теги, и dcc только извлекает эти теги во внешние xml-файлы, и ему все равно, что это за теги. (Обрабатывайте только атрибут cref и нормализуйте ссылку на код). - person Baoquan Zuo; 30.09.2011
comment
P.S. Documentation Insight только упрощает чтение и написание документации. Вы по-прежнему можете следовать приведенным выше рекомендациям и писать теги xmldoc вручную, хотя на самом деле сложно поддерживать правильное форматирование комментариев xmldoc. :) - person Baoquan Zuo; 30.09.2011
comment
@Paul: какими бы ни были возможности, Help Insight по умолчанию распознает только теги, описанные в справке. Таким образом, вы можете добавить все остальные теги в свой исходный код, но кто-то другой со стандартной установкой не сможет их использовать. То, что эти теги можно улучшить загрузкой, здесь не имеет значения, но спасибо за подсказку. - person Rudy Velthuis; 30.09.2011
comment
@RudyVelthuis Да, это так. Наша миссия — распространять расширенный шаблон Help Insight на благо сообщества. :) В будущем мы предоставим БЕСПЛАТНЫЙ пакет документации, который включает настраиваемый шаблон Help Insight и рекомендации. - person Baoquan Zuo; 01.10.2011
comment
@Paul: дело в том, что если я пишу документацию для своих модулей в этих модулях, я не могу предположить, что у кого-то есть расширенный шаблон, поэтому я ограничен тем, что Help Insight предлагает из коробки. - person Rudy Velthuis; 02.10.2011