3 октября 2008 в 00:17

XML документация в C#

.NET*
Приветствую, хабра-дотнетчики!
Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «XML документация» или «Документирующие комментарии XML». Это такие специальные теги XML, которые содержаться в комментариях и описывают свойства или методы в конкретном файле. Так вот, есть по крайней мере три веских причины, почему всегда следует заполнять XML комментарии.


Во-первых, такой подход позволяет стандартизировать комментарии в вашем проекте и, впринцепе, во всех проектах на C#, а стандарты в нашем деле это почти всегда хорошо. Во-вторых, IntelliSense будет автоматически отображать информацию о документированых методах и параметрах, также как и для методов, встроенных во фреймворк. Это очень сильно облегчит работу и сэкономит время и вам и другим разработчикам, работающим с вами. И в-третьих, на этапе компиляции можно сгенерировать XML файл, который будет содержать все комментарии в удобном формате, а с этим файлом уже можно сделать все что угодно.

А теперь мы рассмотрим теги, рекомендованные для использования. Для того, чтобы начать их вводить, нужно сначала поставить "///".

Тег Используется для
<c> одна строка исходного кода
<code> много строк исходного кода
<example> пример использования, можно использовать совместно с тегом <code>
<exception> позволяет указать, какие исключения наш метод может выдавать
<include> позволяет поставить ссылку на файл, в котором содержаться комментарии, используя XPath
<list> обычный список
<para> а это обычный параграф
<param> описания параметра метода, каждый параметр описывается отдельно
<paramref> позволяет указать, что слово внутри тега является параметром
<permission> позволяет описать права доступа к методу
<remarks> дополнительная информация, помимо тега <summary>
<returns> описание того, что метод возвращает
<see> позволяет указывать ссылки
<seealso> текст в секции «Смотри также»
<summary> общее описание
<value> позволяет описывать свойства


Пример:
/// <summary>
/// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
/// </summary>
/// <param name="repeat">Сколько раз передать привет</param>
/// <returns>Сама строка с приветами</returns>
public string HelloHabr(int repeat)
{
     string result = "";
     for (int i = 0; i < repeat; i++)
     {
         result += "Hello, HabraHabr!\n";
     }
     return result;
}




А вот так наш метод будет показан в IntelliSense:

isense1.jpg - image uploaded to Picamatic
isense2.jpg - Picamatic - upload your images
Подробно про все можно почитать как всегда на MSDN.

Ну вот, для начала наверно все. Начинайте пока правильно документировать свой код, а я подготовлю еще пару статей на эту тему, если эта окажется актуальной.
@Maxter
карма
12,3
рейтинг 0,0
Похожие публикации
Самое читаемое Разработка

Комментарии (73)

  • 0
    Все время считал это фичей VS, а оказалось входит в язык :)
    • 0
      Да, причем из дотнетовских только в C#
  • +1
    Я знал об этом, но каюсь: не документирую код.

    Автор, спасибо! После этой статьи я начал проводить полную документацию своих проектов. Сижу вот, описываю =)
    Раньше почему-то не мог собраться с мыслями и не начинал документировать (((
    • +4
      Рад, что сделал мир чуточку лучше ;)
  • 0
    Спасибо, очень познавательно. Хорошо бы побольше статей по фичам студии.
    • +3
      Хотел недавно написать про сниппеты, но про них уже писали, если не читали — почитайте, полезная штука. Я, в свою очередь, постараюсь описать еще некоторые фичи этой чудесной IDE
      • 0
        Про сниппеты читал, но как-то они у меня не прижились. Надо заставлять себя, это действительно удобно, но пока привычка их использовать не появилась.
        Буду ждать дальнейших статей от вас =)
        • 0
          Я из сниппетов пользуюсь только ctor, наверное :)
          Нужно посмотерть что ещё полезного и частоиспользуемого там есть.
          • 0
            Там много чего есть =) Да еще и свои создавать можно. Буду привыкать к ним, полюбому.
          • +1
            Веб-разработчикам, наверное, будет полезен eventh так же как и мне.
    • 0
  • –4
    ИМХО — XML неудобен для человека. Мне тяжело даже phpDoc писать((
    Хоть бы нормальное что-нибудь придумали, а то руки отваливаются всякие @param писать((
    • 0
      Удобства проявляются потом, кода пользуешься задокументированными таким образом библиотеками. К тому же в этих комментариях работает IntelliSense, буковками приходится писать только по делу.

      По поводу удобства для человека — это все потом можно перевести в файлики mht (вроде так называются) и получить документацию как в msdn, что вполне удобно для человека.

      И если заговорили про нормально. Как вам это видится? Какой формат придумать чтобы можно было описать все эти данные и в тоже время совсем не напрягаться?
    • 0
      установите себе VisualAssist или Resharper они облегчат создание XML комментариев до одного клика.
    • 0
      установите себе VisualAssist или Resharper они облегчат создание XML комментариев до одного клика.
      • 0
        не подскажите, какой клик и куда надо сделать в ReSharper? с ходу не нашел
        • 0
          Перед телом метода или класса просто наберите три слеша, и R# вставит шаблон комментария.
          • 0
            это я знал
            вопрос в том, как мышью это провернуть «в один клик», так как озвучил name1ess0ne
            • 0
              мышью это в любом случае делать не надо, будет падать производительность. а три слеша — достаточно быстрый и очевидный шорткат.
              • 0
                почему падать?
                просто хочу узнать секрет «одного клика», меня name1ess0ne заинтриговал
                • 0
                  в R# такой фичи нет.

                  А при использовании мышки для простых операций производительность всегда падает, потому что теряется контекст, нужно искать на экране курсор глазами, требуется время на перенос руки с клавиатуры на мышку и обратно.
                • –1
                  VisualAssist

                  На счет решарпера уже отписал.
          • 0
            Это вставляет VS2008, решарпер вроде не при чем. Хотя может эта фича просто пересекается. А в один клик у меня получается генерить такие комменты в R# 4.1 просто нажав на название метода, слева появляется «лампочка», по ней уже щелкаем и выбираем «generate xml comments». Но тут нужно, чтобы отсутствие этих комментариев вызывало Warnings при компиляции. По-моему, так.

            Подробнее о настройках смогу посмотреть попозже.
        • 0
          Мышью в один клик это делается в VisualAssist, которым я и пользуюсь. Но и в Resharper есть функциональность для вставки XML комментариев, разве не так?
          Кстати вот что еще нашел, думаю многим пригодится.
          www.roland-weigelt.de/ghostdoc/
        • 0
          Если нужны только комментарии, то GhostDoc поможет:
          www.roland-weigelt.de/ghostdoc/
          На методе правой кнопкой и клик по «Document this». GhostDoc многое напишет за Вас. :)
        • 0
          лучше GhostDoc.
          Он по нажатию Cntrl+D+D Автоматически документирует выбранный код и даже описание пытается составить на основе названия метода. (и если в названиях придерживаться правила — только глаголы — даже нормально получается у него :) )
          • 0
            Да, например к методу, который у меня в примере он в summary пишет Helloes Habr :)
            • 0
              Ну так у вас название метода — существительное ;-)
              Вот если бы было SayHelloToHabr
              то гхостдок написал бы: Says hello to habr :)
              • 0
                Да нет, впринцепе Helloes вполне можно перевести как «приветствует», так что все нормально.
    • 0
      Соглашусь. Для меня тоже xml менее читаем чем олд-скул javadoc/phpdoc-комментарии.
  • 0
    У нас в компании есть специальная тулза. Её нужно запускать перед тем, как сабмитить код в систему контроля версий. Она правит проекты в Sollution, изменяя настройки таким образом, что все Warning выскакивают ошибками, и компиляция не проходит. А предупреждения вставляются на такие вещи как: отсутствие XML документации к не private методам, наличие неиспользуемых переменных и т. д. Поначалу непривычно писать, потом привыкаешь, но зато в репозиторий уже попадают коды в очень хорошем виде.

    Хотя я на этапе разработки предпочитаю отключать эту фичу, а документировать все что сделал уже перед сабмитом на сервер.
    • 0
      А что за тулза такая? Порекомендуйте =)
      • 0
        Кем-то из сотрудников написанная много лет назад, так что тут врядли порекомендовать смогу :) Завтра посмотрю детальнее что она в проектах меняет, расскажу.

        Только сразу предупреждаю, могу забыть :)
        • 0
          Спасибо, очень интересно.
          PS Я вам напомню, если что ;)
        • 0
          а исходники есть? :)
          Может того её, в опенсорц? :)
          • 0
            Я даже не знаю, мне досталась как инсталлятор. Теоретически где-то в хранилище должны быть и сорцы, но сомневаюсь, что найду :)
            Да сама программа в общем-то тупа по своей логике, скорее всего берет открытый Sollution, проходится по всем Project которые ему принадлежат и правит ихние настройки. Эти же файлы в виде XML хранятся. Студия после её запуска ещё говорит о том, что Project изменен внешней программой, перезагрузить или оставить таким как есть.

            Завтра выйду на работу — посмотрю. А то в обещаную пятницу закрутился и вспомнил только дома об этом :)
  • 0
    Оценил всю прелесть и крутость XML-комментариев в C#, когда писал диплом. С автором согласен.
  • +3
    Есть удобный plugin для Visual Studio, называется GhostDoc. Умеет сам генерировать комментарии в соответствии с названием методов. Можно делать шаблоны и т. д. Очень удобно.
    • 0
      отличная штука, а решарпер еще потом приглядывает если что то убрано или не добавлено в коммент.

      www.roland-weigelt.de/ghostdoc/

      Просто жмете на название метода/класса/функции/интерфейса и пр. правой кнопкой мыши и выбираете первый пункт: Document This :)
      • 0
        Ну у нас не Решарпер, кстати, за этим следит, а fxCop и StyleCop.
  • 0
    XML-документирующие комментарии? Похоже на стремление впихнуть как можно больше buzzword'ов в продукт. :)
  • 0
    на этапе компиляции можно сгенерировать XML файл, который будет содержать все комментарии в удобном формате, а с этим файлом уже можно сделать все что угодно.

    Это не только «можно», но и «нужно». Если поставлять проект в виде скомпилированной .NET-сборки и ссылаться на нее через Add Reference, то для того, чтобы IntelliSense мог что-то показать, рядом с этой сборкой должен лежать тот самый XML-файл.
  • 0
    Отказался от XML-комментариев в пользу doxygen-style. Теги XML очень сильно загромождают код. Правда, пришлось соответственно и отказаться от поддержки VS для автогенерации тегов, tooltip'ов и т. д. Однако для меня такой комментарий
    /** Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
     *  @param  [in] repeat Сколько раз передать привет
     *  @return Сама строка с приветами
     */

    более понятен, нежели

    /// <summary>
    /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
    /// </summary>
    /// <param name="repeat">Сколько раз передать привет</param>
    /// <returns>Сама строка с приветами</returns>
    
    • 0
      А для меня наоборот. Глаз уже «намётан» давно и я эти "///" комментарии понимаю «сполуслова».

      ЛЮДИ, ПИШИТЕ КАМЕНТЫ:
      1) это в разы облегчает поддержку кода;
      2) сокращает количество комментариев внутри метода (потому что все поля и вызываемые методы подсвечиваются подсказкой, где написано предназнаение члена класса, как на скринах сверху). Вобщем комментарии внутри метода остаются только в случае нестандартности или «не с первого взгляда» интуитивности, как иногда случается в каверзных ситуациях.

      Пишите каменты и на ВСЕ поля, и на ВСЕ классы, а не только на методы.

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

      P.S. Очень тяжело читать C# open source без каментов, попробуйте подфиксить внутренности хотя бы QuickGraph или DockPanel Suite и вы сразу поймете для чего те комментарии нужны!
  • –1
    Даёшь самодокументирующийся код!
    Хватит захламлять код!

    • +1
      Самодокументирующийся код — это действительно клёво, но это нужно при совместной работе надо одним кодом группы людей. XML-документация — это другое. Это те подсказки, что мы должны оставлять для тех, кто не полезет в исходники наших уже готовых сборок, а будет просто линковать их и использовать, реализованные там типы. Не всякий же раз, используя тип из внешней сборки, полезешь буравить его код рефлектором… Как-то так :-)
      • –1
        Ну, да. Вот объясни мне зачем этот камент:?? Вот какая от него польза?
        Как эта функция должна называться в самодокументирующемся коде

        void printHelloHabrNumberOfTimes(int number)

        Сравни вот с этим — где больше «информационного шума»?

        /// /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
        ///
        /// Сколько раз передать привет

        • 0
          а я бы обозвал параметр метода как int times

          • 0
            согласен.
            вот этому и надо учиться, чтобы выбирать однозначные и для всех понятные именна для классов, методов, переменных
          • +1
            именно поэтому его нужно документировать :)
          • 0
            Это только русский язык такой удобный, что можно слово в родительном падеже использовать в качестве названия с малой вероятностью появления неоднозначности. Других «times» заставит лишний раз задуматься «какие такие времена?», «это что, массив/список?» и т. д.

            Иных разрабов хочется заставить комментировать по-русски латинскими буквами (int raz), либо вообще сослать на 1С. :)
        • 0
          А как тогда будет называться входной параметр в случае, если допустимо, чтобы он принимал значения от 1 до 10? ;-)
          • 0
            вот тут действительно можно прокомментировать.
            Хотя как по мне такое решение больше напоминает корявенький дизайн.
            Можно:
            а) создать какой-то enum и передовать его
            б) вести валидацию и просто писать error в лог

            ну, в любом случае «it depends» )
        • 0
          Это все понятно, но писать в лог — это все как дополнительные вещи. Зачем мне писать метод в коде, вызывать его, смотреть что результат не ожидаемый вышел, лезть в лог и смотреть в чем ошибка, потом только исправлять её. Проще посмотреть сразу при написании кода какие допустимые значения.

          Другой вопрос. А куда этот метод пишет? В файл, в лог, в консоль, в Response.OutputStream? Останется известным только вам.

          И опять же. Если вы сгенерируете потом нормальную документацию из этого, то другие разарботчики смогут без проблем её читать, иметь представление что и как работает, для чего все нужно, а потом уже начнуть писать код. Без такой же документации все придется делать методом тыка.

          И ещё, какие исключения этот метод может сгенерировать? InvalidArgumentException, IoException? Или может какое-то свое исключение? Не перехватывать же базовый Exception.

          В общем, писать или не писать комментарии зависит от нескольких вещей. Будет ли кто-то кодом работать ещё, планируется ли это выкладывать в общее пользование, насколько вероятна поддержка кода в будущем. Я для своих каких-то целей когда пишу, то xml комментариями не пользуюсь, а на работе всегда так пишу и понимаю, что не зря.

          А с названиями методов вы правы на 100%, их такими нужно давать как при наличии xml-comments так и без них :) Не комментариями едиными.
          • 0
            1. Если вы думаете, что все кто пишет код постоянно смотрят на quick help, то вы глубоко ошибаетесь.
            2. Лог всегда пишет в лог.
            3. Я вам дал нормальный вариант как ограничить ввод данных другим способом — используйте enum, передавайте всё это дело в классе-обёртке.
            4. Если это настолько кртитично, то киньте свой exception, типа InvalideRangeException.
            • +1
              Мне кажется 99% людей, кто пользуется новой какой-то библиотекой смотрят на подсказки в IntelliSense, что делают функции, зачем те или иные параметры… У меня Ctrl + Shift + Space одно из самых частоиспользуемых сочетаний клавиш.

              Не спорю что лог пишет туда, но зачем мне узнавать о причине ошибки в рантайме, если я могу её предотвратить на этапе написания?

              Число принимаемое может быть ограничено по определенному диапазону. На них перечислений не напасешься.

              Я о своем исключении и писал. Вот только если это мой класс будет, как вы узнаете как он называется? Опять в рантайме?

              Я понимаю, что писать эту всю документацию лениво, но не могу понять вашу категоричную точку зрения. Я когда начал работать с jquery, то подключил для него IntelliSense с описанием всех методов и параметров. Таким образом получилось писать сразу, практически не обращаясь ко всяким справочникам. Мне нравится пользоваться хорошо написанным кодом, поэтому стараюсь делать такой же для других.
              • 0
                В любых IDE такая комбинация как «Ctrl + Shift + Space» выдаёт сигнатуру метода, а уж никак не описание ограничения каждого параметра.
                Давайте так, что более юзабельно

                /// <summary>
                /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
                /// </summary>
                /// <param name=«repeat»>Сколько раз передать привет</param>
                /// <returns>Сама строка с приветами
                public string foo(int i)
                {
                string result = "";
                for (int i = 0; i < repeat; i++)
                {
                result += «Hello, HabraHabr!\n»;
                }
                return result;
                }

                Или void printHelloHabrNumberOfTimes(int number)?

                Теперь по поводу библиотек. Библиотека для того и создаётся, чтобы использоватеться всеми по полной. В отличае от коментирования метода, который скорее всего вызоветься вами один раз и всё! Вы потратите больше времени на написание комента, чем полезного кода.
                • 0
                  Зачем вы в крайности? Я ещё в первом комментарии написал
                  А с названиями методов вы правы на 100%, их такими нужно давать как при наличии xml-comments так и без них

                  Одно не противоречит другому. Вы ведь видели в сигнатуре каждого метода, описание отдельного параметра? Там можно писать и об ограничениях. В описании метода можно указать какие исключения он вызывает. И пользуясь такими «сигнатурами», вы получаете исчерпывающую информацию о вызываемом методе.

                  Я вот просто сейчас вижу, что вы немного не о тех вещах говорите. Вы правильно поняли, как xml-comments работают? Это в первую очередь нужно не для того, чтобы вы не понимал из вот этого в коде за что метод отвечает

                  /// <summary>
                  /// Этот метод передаёт привет ХабраХабру столько раз, сколько скажите.
                  /// </summary>
                  /// <param name=«repeat»>Сколько раз передать привет</param>
                  /// <returns>Сама строка с приветами


                  А для того, чтобы вашими библиотеками потом было удобно пользоваться всем и по полной, с привильно описаными сигнатурами методов и так далее. И этот ваш труд в комментариях ещё как оценен будет.

                  На сим со своей стороны беседу останавливаю, так как вижу что мы или в разных плоскостях рассуждаем, или говорим о разных вещах, так как не сходимся во мнениях.

                  Вы к стати на C# работаете?
                  • 0
                    нет на java, но совсем не трудно догадаться, что это ничто иное как подобие javadoc и из него потом можно нагенерить документацию, которой с 99% вероятностью потом никто пользоваться не будет )
  • +2
    Ну отныне комментарии писать станет даже интереснее

    Такие комментарии генереируются в VB.NET если ввести три апострафа
  • 0
    Отличная возможность. А для генерации документации по XML-комментариям можно использовать тулзу Sandcastle от MS и Sandcastle Help File Builder (графическая оболочка для Sandcastle).
  • 0
    В SharpDevelop, кстати, тоже очень неплохая помогалка для генерации документирующих комментариев.
  • 0
    FAQ по документирующим комментариям в C#
    rsdn.ru/article/devtools/CSxmlcmnt.xml

    Sandcastle — Новый генератор документации для .NET
    rsdn.ru/article/helpsystems/Sandcastle.xml
  • 0
    Автору спасибо. Забыли только упомянуть о коментах в .js коде, благо 2008 студия уже их прекрасно поддерживает и воспроизводит.
  • 0
    Вставлю свои пять копеек.

    list — это не просто список. У него может быть тип (type = bullet|table). item — элементы списка, внутри них можно ещё использовать term — description.

    <para>Структура таблицы:</para>
    <list type="table">
      <listheader>
        <term>Название</term>
        <description>Описание</description>
      </listheader>
      <item><term>user_id</term><description>Int32. Идентификатор пользователя.</description></item>
      <item><term>user_name</term><description>String. Имя пользователя.</description></item>
    </list>
    


    Минус: Object Browser не отупляет такие конструкции — выводит всё одной строкой без разделителей даже.
    Плюсы: R# (Ctrl + Q) и Sandcastle отупляют :)
  • 0
    Оказывается в CDS/BDS (Delphi 2005-2009) это тоже есть. Приятно удивлен.
  • 0
    Можете меня пинать, но все это было еще аж для VS2003, причем там был даже пункт типа Create HTML Documentation или что-то вроде того. Почему его убрали в 2005 и 2008 мне лично не понятно.
    А чем вызван такой ажиотаж я вообще понять не могу. Про это в каждой книге Троелсена написано.
    • 0
      Пункт Create HTML Documentation остался и в 2005 и 2008, а написано для тех, кто возможно не знал, а такие всегда есть :)
      • 0
        Да? А где??
        • 0
          Тоже весьма удивлен.
          Сам пользуюсь Sandcastle + Sandcastle Help File Builder
      • 0
        Действительно, а где?

Только полноправные пользователи могут оставлять комментарии. Войдите, пожалуйста.