Из тех, кто писал че-нить на шарпе, использовали ли средства XML (теги) для документирования кода? Полезная штука, скажу я. Автоматически генерится html'ы с описанием классов...

Ну, мне пока не приходилось.
Не пояснишь, в чем, собственно, "полезность"?

Я сейчас как раз читаю Троелсена в этом месте..

Цитата(Kurt @ 10.4.2005, 09:07)

Не пояснишь, в чем, собственно, "полезность"?

Документацию очень быстро генерить из комментариев можно.

Цитата(Kurt @ 10.4.2005, 19:07)

Не пояснишь, в чем, собственно, "полезность"?

Например

Цитата(chipset @ 10.4.2005, 19:28)

Документацию очень быстро генерить из комментариев можно.

Ты пишешь документированный код. Сами теги можно скрывать в регионы, они не будут занимать много места. Подводишь указатель к строке с документиованием - и читаешь. Документация будет автоматически создаваться на основе этого когда - она будет представлять из себя html проект. Это будет, скорее, руководство программиста.


Пожалуйста:

Код

using System; namespace Queuing_System {     #region Документирование класса FetchingManagers     /// <summary>     ///    Инкапсулирует диспетчеры выборки из буфера заявок.     /// </summary>     /// <remarks>     ///    1. Организует дисциплину выборки завок из буфера.     ///    <newpara>     ///    2. Организует дисциплину выбра прибора на обслуживание.     ///    </newpara>     ///    <newpara>     ///    Наследует переменные <code>bufer</code> и <code>call</code>.     ///    </newpara>     /// </remarks>     #endregion     public class FetchingManagers : Managers     {         #region Документирование переменнной packet         /// <summary>         ///    Номер источника, от которого принимается текущий пакет.         /// </summary>         /// <remarks>         ///    Управляется свойством <code>Packet</code>.         /// </remarks>         #endregion         private int packet;         #region Документирование переменнной timeOfSingularEvent         /// <summary>         ///    Время особого события при постановке заявки на обслуживание.         /// </summary>         /// <remarks>         ///    Управляется свойством <code>TimeOfSingularEvent</code>.         /// </remarks>         #endregion         private double timeOfSingularEvent;         #region Документирование конструктора по умолчанию FetchingManagers         /// <summary>         ///    Конструктор по умолчанию.         /// </summary>         /// <param name="paramBuffer">         ///    Буфер.         /// </param>         /// <returns>         ///    Ничего не возвращает.         /// </returns>         /// <remarks>         ///    Принимает буфер, с которым будет работать.         ///    <newpara>         ///    Использует конструктор базового класса по умолчанию.         ///    </newpara>         /// </remarks>         #endregion         public FetchingManagers( Buffers paramBuffer ) : base()         {             Packet = 1;             timeOfSingularEvent = 0;             Buffer = paramBuffer;         }

В самой студии это видется следующим образом:

Код

using System; namespace Queuing_System {     [i]Документирование класса FetchingManagers[/i]     public class FetchingManagers : Managers     {         [i]Документирование переменнной packet[/i]         private int packet;         [i]Документирование переменнной timeOfSingularEvent[/i]         private double timeOfSingularEvent;         [i]Документирование конструктора по умолчанию FetchingManagers[/i]         public FetchingManagers( Buffers paramBuffer ) : base()         {             Packet = 1;             timeOfSingularEvent = 0;             Buffer = paramBuffer;         }

На то, что выделено тегами /, подводишь мышу - и всплывает hint, или как его там, с текстом этого региона. Сами регионы можно скрывать, раскрывать. Это будет все сейвиться и до следующего сенанса работы с солюшеном, конечно.

Цитата(chipset @ 10.4.2005, 19:28)

Я сейчас как раз читаю Троелсена в этом месте..

Респект. Сам по нему изучал. Можешь еще Шилдта посмотреть. Там тоже есть - в приложении.

Хотя что это я... в свое время составил методу по этому делу на основе инфы из MSDN и всем раздавал, кто спрашивал. На английском, конечно, но всем помогает. Смотрите приартаченный файл.

Дам несколько советов.

Не все теги юзаются в html страничке, т.к. Code Coment Web Report - это лишь одно из применений тегов XML. В методе указано, какие теги XML будут восприниматься при создании html-страниц.

При создании самой документации (Tools -> Build Comment Web Pages) лучше все же указать, что надо использовать теги html. Они по-умолчанию этого не ставят - типа из-за защиты, и отображают теги на равне с обычным текстом. В общем галку первую лучше снять.

Ну и наконец, когда вы пробилдите (Tools -> Build Comment Web Pages), скорее всего документация не будет отображаться, т.к. эта страница будет принадлежать к Ограниченным узлам. Можете добавить ее в "хорошие узлы IE", или дать власть Ограниченным, на время конечно. У самого с этим проблемы.

Присоединённый файл ( Кол-во скачиваний: 15 )
 XML_Documentation.rar

Вот, собственно, пример полученной html-документации. Замечу: полностью автоматически!
Пришлось урезать 2/3 страниц - не умешался в 50 Кб.

Присоединённый файл ( Кол-во скачиваний: 12 )
 CodeCommentReport.rar

Можно юзать для генерации документации NDoc, тогда можно выставить кучу настроек и получить документацию в виде CHM, LaTex, "MSDN" HTML и в других форматах. Кстати, мсдн-овский стиль в автогенерируемой документации - очень крутая штука .

Насчёт полезности - скажу, что при наличии таких комментариев, во-первых IntelliSense "подсказывает" о каждом классе, методе, аргументе при вводе исходного кода, а во-вторых, в случае когда пишется нечто вроде компонента, который потом будет продаваться за деньги (или просто хороший open-source проект), то в состав дистрибутива обычно (читай: всегда) включается файл справки (class reference), сгенерированный по комментариям в коде.

Наконец, в комментариях можно использовать кучу разных фич, все они подробно описаны в мсдн. Вот лишь некоторые из них:
1) Ссылка на класс, метод, свойство (see cref="..."). В файле справки заменяется URL-ссылкой на раздел справки, посвящённый тому, что указано в кавычках;
2) Включение внешнего фрагмента из XML-файла (include ...) - в таких файлах можно хранить примеры кода, подробное описание и др. текст, который не хочется включать в исходный код из-за его громоздкости, даже при наличии регионов;
3) HTML-теги для форматирования текста (курсив, жирный, подчёркнутый текст и много другое).

Цитата(mr @ 11.4.2005, 08:08)

Можно юзать для генерации документации NDoc, тогда можно выставить кучу настроек и получить документацию в виде CHM, LaTex, "MSDN" HTML и в других форматах.

Это все по тем же XML, коментам как я понял?
На счет полезностей - знаю, офигенно круто. NDoc теперь хочу попробовать.

Цитата(Cr @ 11.4.2005, 12:52)

Это все по тем же XML, коментам как я понял?

да

Чё то не могу найти, как сделать html в Visual Studio 2005. Xml нашёл, а html где?

Отдельными тулзами, типа SandCastle. Этот вопрос уже много раз подымался.

Через месяц ты понимаешь значение своего кода без проблем  .