Comments 29
отлично! спасибо
Спасибо за очень подробное описание. Сразу сходил посмотреть, что за компоненты продаете :) Они кормят или это так, подработка?
отличное описание! спасибо, многие моменты уже забыл)
Исчерпывающе. Спасибо.
ваши слова, да многим разработчикам в уши… с первого курса!
Ну ни одна маленькая/средняя компания не хочет писать не то, чтобы документацию или структуру программы, а банальные комментарии ко всему коду и форматировать его.
Как можно скорость разработки продукта и скорость «вхождения» в проект для новых девелоперов променять на ленивое «программист должен кодить, а не программировать» или «а зачем комментарии, тут же и так все понятно» ??!!!
Дико…
Сегодня глаза сломал разбираясь в каше двухлетней давности какого-то кодера.
Ну ни одна маленькая/средняя компания не хочет писать не то, чтобы документацию или структуру программы, а банальные комментарии ко всему коду и форматировать его.
Как можно скорость разработки продукта и скорость «вхождения» в проект для новых девелоперов променять на ленивое «программист должен кодить, а не программировать» или «а зачем комментарии, тут же и так все понятно» ??!!!
Дико…
Сегодня глаза сломал разбираясь в каше двухлетней давности какого-то кодера.
За всех то не говорите. У нас, например по форматированию кода суровые правила — к SVN-у прикручен StyleCop (в нем задаётся шаблон по форматированию кода)
И криво отформатированный код разработчик даже не сможет закоммитить :)
Возможно о работе такой связки позже статейку напишу
И криво отформатированный код разработчик даже не сможет закоммитить :)
Возможно о работе такой связки позже статейку напишу
С удовольствием прочитал бы про связку SVN и StyleCop. То есть по-отдельности я их использую, а вместе пока не доводилось. Насколько понимаю, там используются хуки SVN?
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Обязательно напишите такую статью. Очень интересно.
за всех и не говорю ('… да многим разработчикам ...').
Радостно, что есть фирмы, в которых к разработке подходят серьезно
Радостно, что есть фирмы, в которых к разработке подходят серьезно
UFO just landed and posted this here
Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции IntelliSense в Visual Studio отображать описания для методов в момент набора пользователем кода.
А мне казалось, что для этого не нужно прикладывать файл с xml-комментариями…
Добавлю, что при включении генерации файла xml-документации, компилятор (по крайней мере C#) начинает генерировать warning'и на все публичные элементы без xml-комментариев. Довольно удобно.
GhostDoc не продвинулся в плане тега Exception?
/// Thrown when...
public void DoSomething() {… }
Всегда хотел какие-нибудь средства автоматически-полуавтоматически описать исключения гененируемые методом
/// Thrown when...
public void DoSomething() {… }
Всегда хотел какие-нибудь средства автоматически-полуавтоматически описать исключения гененируемые методом
парсер тег сожрал… в общем отсюда msdn.microsoft.com/en-us/library/w1htk11d.aspx
К сожалению, в плане автоматического прописывания исключений в GhostDoc ничего не поменялось.
Я сам очень хочу найти способ автоматически документировать исключения.
Я сам очень хочу найти способ автоматически документировать исключения.
У нас принято использовать синтаксис комментариев совместимый с Doxygen
Это обеспечивает единообразие стилей и способов генерации документации на разных платформах и языках.
Это обеспечивает единообразие стилей и способов генерации документации на разных платформах и языках.
Выскажу свое мнение.
Я вот лет 5 назад тоже увидел эту программулину и давай сразу тыкать, применять для всего. Но потом задумался — а кому нафик нужна эта автоматически сгенеренная документация? Особенно если там нет внятных примеров использования кода а всего по 2-3 очевидных объяснения к методу, которые можно и так понять из его названия.
Даже проводил соц. опрос среди разработчиков: полезна эта документация всего 10% разработчиков.
Ну сами подумайте. Скачали какую-нибудь либу. Открываете папку — там 150 Кб либа и 2 Мб документации. В документации только названия методов и очевидное их описание. Ну какой смысл в ТАКОЙ документации? Станете ли вы ее читать?
Нужна документация иного рода, где описывается процесс использования в общем + приведены конкретные примеры. И поменьше воды.
Мне гораздо полезнее примеры использования. Вот на это стоит потратить время. А заниматься пустотой смысла нет. То что так делают все — это не повод транжирить время.
Я вот лет 5 назад тоже увидел эту программулину и давай сразу тыкать, применять для всего. Но потом задумался — а кому нафик нужна эта автоматически сгенеренная документация? Особенно если там нет внятных примеров использования кода а всего по 2-3 очевидных объяснения к методу, которые можно и так понять из его названия.
Даже проводил соц. опрос среди разработчиков: полезна эта документация всего 10% разработчиков.
Ну сами подумайте. Скачали какую-нибудь либу. Открываете папку — там 150 Кб либа и 2 Мб документации. В документации только названия методов и очевидное их описание. Ну какой смысл в ТАКОЙ документации? Станете ли вы ее читать?
Нужна документация иного рода, где описывается процесс использования в общем + приведены конкретные примеры. И поменьше воды.
Мне гораздо полезнее примеры использования. Вот на это стоит потратить время. А заниматься пустотой смысла нет. То что так делают все — это не повод транжирить время.
Я некоторое время назад был склонен думать как вы. Но теперь изменил свое мнение.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
Наверное зависит от того, будете ли вы для каждого метода приводить примеры и полезное описание. Иначе получается слишком много воды, а это плохо. Кто будет открывать и просматривать всем члены всех классов, дабы найти те 3-4 нещастных метода, где вы разместите примеры?
Просмотрел LibTiff.Net. Красота! Глаз нельзя отвести, как красиво. И себе захотелось так сделать… А вот толку — нуль (я имею в виду та часть, где неймспейсы и классы, а не где примеры и общее описание). Реально, если бы я использовал их библиотеку — мне бы были интересны лишь примеры и общее описание. Остальное легче глянуть в intellisense.
Ну разве что для красоты, для «крутости» имеет смысл это сделать. Чтоб же все видели, что я таки не отстаю от жизни и как все делаю абсолютно никому не нужную автогенеренную документацию (это ж круто!).
И еще одно. MSDN врядли писалась прямо в коде .Net. Это не удобно. Все примеры, все примечания туда втулить. У них наверняка более удобный инструмент. Вот от чего-либо подобного я б не отказался. А автогенеренная документация ТОЛЬКО по коду — не есть гуд. Тем более как ее переводить на другие языки?
Просмотрел LibTiff.Net. Красота! Глаз нельзя отвести, как красиво. И себе захотелось так сделать… А вот толку — нуль (я имею в виду та часть, где неймспейсы и классы, а не где примеры и общее описание). Реально, если бы я использовал их библиотеку — мне бы были интересны лишь примеры и общее описание. Остальное легче глянуть в intellisense.
Ну разве что для красоты, для «крутости» имеет смысл это сделать. Чтоб же все видели, что я таки не отстаю от жизни и как все делаю абсолютно никому не нужную автогенеренную документацию (это ж круто!).
И еще одно. MSDN врядли писалась прямо в коде .Net. Это не удобно. Все примеры, все примечания туда втулить. У них наверняка более удобный инструмент. Вот от чего-либо подобного я б не отказался. А автогенеренная документация ТОЛЬКО по коду — не есть гуд. Тем более как ее переводить на другие языки?
Можно включить файл проекта (*.shfbproj) от Sandcastle Help File Builder в solution Visual Studio, однако в настоящее время нет возможности использовать его как полноценный проект.
Вроде есть вот такой полноценный проект для VS, который генерирует документацию с помощью Sandcastle: docproject.codeplex.com/
Годика этак четыре назад писал статью про Sandcastle:
rsdn.ru/article/helpsystems/Sandcastle.xml
rsdn.ru/article/helpsystems/Sandcastle.xml
А еще если написать тройной слеш (///) Visual Studio сама вставит теги (summary, params, return) и останется только добавить для них описание.
Активно пользуюсь вашей статьей для старта с Sandcastle, а заодно и документацией к docotic, в качестве живого примера — спасибо!
Однако в большинстве случаев сгенерированный xml-файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml-файл так, чтобы в нем остались только описания к публичным методам.
Может не внимательно читал, но чето не нашел где в статье про это написано?
Затруднялся с написанием документации для проекта. Теперь есть хорошее руководство — спасибо.
Sign up to leave a comment.
Создание документации в .NET