Создание документации в .NET

[@XaocCPS]

отлично! спасибо

[@outcoldman]

Спасибо за очень подробное описание. Сразу сходил посмотреть, что за компоненты продаете :) Они кормят или это так, подработка?

[@webus]

отличное описание! спасибо, многие моменты уже забыл)

[@sergeyzwezdin]

Исчерпывающе. Спасибо.

[@asArtem]

ваши слова, да многим разработчикам в уши… с первого курса!

Ну ни одна маленькая/средняя компания не хочет писать не то, чтобы документацию или структуру программы, а банальные комментарии ко всему коду и форматировать его.
Как можно скорость разработки продукта и скорость «вхождения» в проект для новых девелоперов променять на ленивое «программист должен кодить, а не программировать» или «а зачем комментарии, тут же и так все понятно» ??!!!
Дико…

Сегодня глаза сломал разбираясь в каше двухлетней давности какого-то кодера.

[@maseal]

За всех то не говорите. У нас, например по форматированию кода суровые правила — к SVN-у прикручен StyleCop (в нем задаётся шаблон по форматированию кода)
И криво отформатированный код разработчик даже не сможет закоммитить :)
Возможно о работе такой связки позже статейку напишу

[@Bobrovsky]

С удовольствием прочитал бы про связку SVN и StyleCop. То есть по-отдельности я их использую, а вместе пока не доводилось. Насколько понимаю, там используются хуки SVN?
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.

[@maseal]

В общем то да, основано на pre-commit хуках.
Чужими SVN-хостингами не пользовался, поэтому не в курсе какие средства управления они предоставляют. Но в любом случае сомневаюсь, что там получится это настроить

[@tangro]

Обязательно напишите такую статью. Очень интересно.

[@asArtem]

за всех и не говорю ('… да многим разработчикам ...').

Радостно, что есть фирмы, в которых к разработке подходят серьезно

[@Idsa]

Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции IntelliSense в Visual Studio отображать описания для методов в момент набора пользователем кода.

А мне казалось, что для этого не нужно прикладывать файл с xml-комментариями…

Добавлю, что при включении генерации файла xml-документации, компилятор (по крайней мере C#) начинает генерировать warning'и на все публичные элементы без xml-комментариев. Довольно удобно.

[@Bobrovsky]

Файл с xml-комментариями можно не прикладывать, но тогда вся информация для IntelliSense будет добываться из сборки через reflection. В сборке, откомпилированной в конфигурации Release, информации не очень много. В итоге работать со сборкой будет менее удобно.

[@paranoik]

GhostDoc не продвинулся в плане тега Exception?

/// Thrown when...
public void DoSomething() {… }

Всегда хотел какие-нибудь средства автоматически-полуавтоматически описать исключения гененируемые методом

[@paranoik]

парсер тег сожрал… в общем отсюда msdn.microsoft.com/en-us/library/w1htk11d.aspx

[@Bobrovsky]

К сожалению, в плане автоматического прописывания исключений в GhostDoc ничего не поменялось.
Я сам очень хочу найти способ автоматически документировать исключения.

[@Vile55]

У нас принято использовать синтаксис комментариев совместимый с Doxygen
Это обеспечивает единообразие стилей и способов генерации документации на разных платформах и языках.

[@codecity]

Выскажу свое мнение.

Я вот лет 5 назад тоже увидел эту программулину и давай сразу тыкать, применять для всего. Но потом задумался — а кому нафик нужна эта автоматически сгенеренная документация? Особенно если там нет внятных примеров использования кода а всего по 2-3 очевидных объяснения к методу, которые можно и так понять из его названия.

Даже проводил соц. опрос среди разработчиков: полезна эта документация всего 10% разработчиков.

Ну сами подумайте. Скачали какую-нибудь либу. Открываете папку — там 150 Кб либа и 2 Мб документации. В документации только названия методов и очевидное их описание. Ну какой смысл в ТАКОЙ документации? Станете ли вы ее читать?

Нужна документация иного рода, где описывается процесс использования в общем + приведены конкретные примеры. И поменьше воды.

Мне гораздо полезнее примеры использования. Вот на это стоит потратить время. А заниматься пустотой смысла нет. То что так делают все — это не повод транжирить время.

[@Bobrovsky]

Я некоторое время назад был склонен думать как вы. Но теперь изменил свое мнение.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?

Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.

Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.

[@codecity]

Наверное зависит от того, будете ли вы для каждого метода приводить примеры и полезное описание. Иначе получается слишком много воды, а это плохо. Кто будет открывать и просматривать всем члены всех классов, дабы найти те 3-4 нещастных метода, где вы разместите примеры?

Просмотрел LibTiff.Net. Красота! Глаз нельзя отвести, как красиво. И себе захотелось так сделать… А вот толку — нуль (я имею в виду та часть, где неймспейсы и классы, а не где примеры и общее описание). Реально, если бы я использовал их библиотеку — мне бы были интересны лишь примеры и общее описание. Остальное легче глянуть в intellisense.

Ну разве что для красоты, для «крутости» имеет смысл это сделать. Чтоб же все видели, что я таки не отстаю от жизни и как все делаю абсолютно никому не нужную автогенеренную документацию (это ж круто!).

И еще одно. MSDN врядли писалась прямо в коде .Net. Это не удобно. Все примеры, все примечания туда втулить. У них наверняка более удобный инструмент. Вот от чего-либо подобного я б не отказался. А автогенеренная документация ТОЛЬКО по коду — не есть гуд. Тем более как ее переводить на другие языки?

[@dima117]

Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект.

Вроде есть вот такой полноценный проект для VS, который генерирует документацию с помощью Sandcastle: docproject.codeplex.com/

[@Bobrovsky]

Да, действительно есть такой альтернативный SHFB-у проект (о нем есть упоминание в статье). К сожалению, у него есть свои недостатки.

Я работал и с DocProject, и с Sandcastle Help File Builder и пришел к выводу, что второй нравится мне больше.

[@dima117]

прошу прощения, когда писал комментарий, случайно пропустил упоминание :)
кстати, спасибо за отличную статью

[@nzeemin]

Годика этак четыре назад писал статью про Sandcastle:
rsdn.ru/article/helpsystems/Sandcastle.xml

[@leon4uk]

А еще если написать тройной слеш (///) Visual Studio сама вставит теги (summary, params, return) и останется только добавить для них описание.

[@GoodwinNK]

Активно пользуюсь вашей статьей для старта с Sandcastle, а заодно и документацией к docotic, в качестве живого примера — спасибо!

[@leo_habr]

Однако в большинстве случаев сгенерированный xml-файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml-файл так, чтобы в нем остались только описания к публичным методам.

Может не внимательно читал, но чето не нашел где в статье про это написано?

[@Bobrovsky]

Про это написано в начале раздела «Генерируем файл документации». Можно поискать строчку «IntelliSense Component» (без кавычек).

[@LefiMind]

Затруднялся с написанием документации для проекта. Теперь есть хорошее руководство — спасибо.