Я некоторое время назад был склонен думать как вы. Но теперь изменил свое мнение.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
К сожалению, в плане автоматического прописывания исключений в GhostDoc ничего не поменялось.
Я сам очень хочу найти способ автоматически документировать исключения.
Файл с xml-комментариями можно не прикладывать, но тогда вся информация для IntelliSense будет добываться из сборки через reflection. В сборке, откомпилированной в конфигурации Release, информации не очень много. В итоге работать со сборкой будет менее удобно.
С удовольствием прочитал бы про связку SVN и StyleCop. То есть по-отдельности я их использую, а вместе пока не доводилось. Насколько понимаю, там используются хуки SVN?
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Можно часть директив препроцессора оставить, об этом написано в статье. Но я рекомендую все-таки удалить все директивы, которые используются для создания разных вариантов программы/библиотеки, чтобы облегчить тестирование в процессе переноса.
Если есть необходимость, то можно потом добавить такие директивы снова.
Все зависит от ситуации. Если портируется собственный код компании (по какой-либо причине), то исправлять ошибку будет та же команда, что писала и оригинальный код. Если же портируется какая-то сторонняя библиотека или программа, то тут надежда только на свои силы / силы тех, кто будет пользоваться новой версией (если это разработчики и новая версия доступна в исходниках).
Поэтому я ни в коем случае не призываю портировать все, до чего дотянутся руки, а лишь описал способ, которым это можно сделать, если такая необходимость есть.
Спасибо за пункт 1). Не знал, что можно использовать goto case x / goto default.
Что касается пункта 2), то тут дело вкуса. Я в статье написал, что такие конструкции «я предпочитаю встраивать». То есть это мой совет/привычка, это не требование.
В c# тоже можно использовать нативные dll. Другое дело, что такой подход имеет свои ограничения: он часто неприменим на веб-серверах (особенно в случае использования shared hosting), для некоторых приложений весьма вероятны проблемы, если идет частый обмен данными большого объема между managed и unmanaged кодом. В Silverlight приложениях такой подход вообще неприменим.
Потому я и описал этот способ, что столкнулся с невозможностью использовать p/invoke или COM Interop.
Конечно, возможна ситуация, что после трансформации код начнет работать медленнее. Об этом и в статье написано. Поэтому описанный способ ни в коем случае не серебрянная пуля.
Все зависит от требований. То есть если нужно сделать простую консольную программу, которая использует стороннюю unmanaged dll, то можно обойтись и p/invoke (даже врэппер никакой не нужен). Если требования другие (например, возможность запуска в medium trust режиме), то и решения требуются другие.
В статье изложен способ трансформации кода, но не затронута тема необходимости такой трансформации. Иногда такая необходимость есть, иногда нет.
Я работал и с DocProject, и с Sandcastle Help File Builder и пришел к выводу, что второй нравится мне больше.
Дело ведь в том насколько полна документация, а не в том, чем она сгенерирована. MSDN вот тоже автоматически генерируется и разве можно сказать, что эта документация не нужна?
Примеры использования и все прочее никто не запрещает создавать. Эта информация нужна и полезна. Дело как раз в том, что одно не исключает другого и документация, созданная из комментариев в исходниках, легко может быть дополнена примерами и какими-то еще описаниями.
Можете поискать в гугле LibTiff.Net. Это опенсоурсная библиотека, для которой документация сделана описанным в статье способом. Насколько получившаяся документация (а она содержит в том числе примеры использования) полезна — решать вам. Может быть ваше мнение по поводу такого способа документирования изменится.
Я сам очень хочу найти способ автоматически документировать исключения.
Еще интересно, будет ли ваш подход работать на svn-хостингах типа code.google.com.
Если есть необходимость, то можно потом добавить такие директивы снова.
Поэтому я ни в коем случае не призываю портировать все, до чего дотянутся руки, а лишь описал способ, которым это можно сделать, если такая необходимость есть.
Что касается пункта 2), то тут дело вкуса. Я в статье написал, что такие конструкции «я предпочитаю встраивать». То есть это мой совет/привычка, это не требование.
Потому я и описал этот способ, что столкнулся с невозможностью использовать p/invoke или COM Interop.
В статье изложен способ трансформации кода, но не затронута тема необходимости такой трансформации. Иногда такая необходимость есть, иногда нет.