Версия для печати темы
Нажмите сюда для просмотра этой темы в оригинальном формате
Форум программистов > Общие вопросы по .NET и C# > XML документирование


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

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

Автор: chipset 10.4.2005, 19:28
Я сейчас как раз читаю Троелсена в этом месте.. smile

Цитата(Kurt @ 10.4.2005, 09:07)
Не пояснишь, в чем, собственно, "полезность"?

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

Автор: Cr@$h 10.4.2005, 20:13
Цитата(Kurt @ 10.4.2005, 19:07)
Не пояснишь, в чем, собственно, "полезность"?


Например

Цитата(chipset @ 10.4.2005, 19:28)
Документацию очень быстро генерить из комментариев можно.


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

smile
Пожалуйста:

Код

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", или дать власть Ограниченным, на время конечно. У самого с этим проблемы. smile

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

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

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

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

Автор: Cr@$h 11.4.2005, 12:52
Цитата(mr @ 11.4.2005, 08:08)
Можно юзать для генерации документации NDoc, тогда можно выставить кучу настроек и получить документацию в виде CHM, LaTex, "MSDN" HTML и в других форматах.

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

Автор: mr.DUDA 11.4.2005, 14:35
Цитата(Cr @ 11.4.2005, 12:52)
Это все по тем же XML, коментам как я понял?

да

Автор: anonym 24.1.2007, 17:40
Чё то не могу найти, как сделать html в Visual Studio 2005. Xml нашёл, а html где?

Автор: mr.DUDA 24.1.2007, 21:11
Цитата(anonym @  24.1.2007,  16:40 Найти цитируемый пост)
Чё то не могу найти, как сделать html в Visual Studio 2005. Xml нашёл, а html где?

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

Автор: Exception 29.1.2007, 14:41
Цитата(Kurt @  10.4.2005,  20:07 Найти цитируемый пост)
Не пояснишь, в чем, собственно, "полезность"? 


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

Powered by Invision Power Board (http://www.invisionboard.com)
© Invision Power Services (http://www.invisionpower.com)