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

    Приветствую, хабра-дотнетчики!
    Сегодня речь пойдет об одной интересной и полезной возможности языка С#, которая поможет нам в документировании кода. Она называется «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.

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

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

      Автор, спасибо! После этой статьи я начал проводить полную документацию своих проектов. Сижу вот, описываю =)
      Раньше почему-то не мог собраться с мыслями и не начинал документировать (((
      • +4
        Рад, что сделал мир чуточку лучше ;)
      • 0
        Спасибо, очень познавательно. Хорошо бы побольше статей по фичам студии.
        • +3
          Хотел недавно написать про сниппеты, но про них уже писали, если не читали — почитайте, полезная штука. Я, в свою очередь, постараюсь описать еще некоторые фичи этой чудесной IDE
          • 0
            Про сниппеты читал, но как-то они у меня не прижились. Надо заставлять себя, это действительно удобно, но пока привычка их использовать не появилась.
            Буду ждать дальнейших статей от вас =)
            • 0
              Я из сниппетов пользуюсь только ctor, наверное :)
              Нужно посмотерть что ещё полезного и частоиспользуемого там есть.
              • 0
                Там много чего есть =) Да еще и свои создавать можно. Буду привыкать к ним, полюбому.
                • +1
                  Веб-разработчикам, наверное, будет полезен eventh так же как и мне.
            • –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
                                                                            Действительно, а где?

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