MSDN.WhiteKnight - Stack Overflow answers
Ответ на "Как правильно сообщить важную информацию в документации?"
Answer 1018313
По сути, это дело должно быть в ремарках, но тогда вопрос — ремарки видно только из Object Explorer'a, и не факт, что все туда заглядывают (думаю, есть вообще те, кто никогда туда не заглядывает).
Естественно, не заглядывают. Если речь идет о публичном API библиотеки, он должен иметь полноценную документацию, в виде веб-сайта или текстового документа, где вы можете привести всю необходимую информацию в том виде, в котором считаете нужным. На те крохи, которые видны в студии, полагаться не приходится. Для генерации документации на основе XML-комментариев можно использовать, например, DocFX.
Информацию о том, что параметр не может быть null, можно поместить и в summary параметра, если это по какой-то причине важно. Но обычно там это будет только мусором. Если параметр - это ссылка на буфер, в который должны быть возвращены данные, он очевидно не может быть null. Поэтому достаточно лишь указать в remarks конкретное поведение, когда null все же передан.
В моем случае происходит вызов COM методов, я не могу бросать исключения, все что могу сделать это возвращать код который отдает COM не больше не меньше.
Это наводит на мысль об архитектурной ошибке. Если вы создаете управляемую обертку для COM-классов, вы не должны оставлять детали реализации COM торчащими наружу через публичные API. Вместо этого вы должны предоставлять высокоуровневые классы, которые работают по правилам C# - т.е., бросают ArgumentNullException при некорректно переданном null. Все детали реализации COM должны быть private или internal. Ну, если только вы не создаете коллекцию деклараций COM Interop, наподобие https://github.com/JeremyKuhne/WInterop
Content is retrieved from StackExchange API.
Auto-generated by ruso-archive tools.