классы csharp "наследуют" документацию xml, как классы java?

Question

Я добавляю комментарии к некоторому коду csharp и использую язык xml, предоставляемый .net (или чем-то еще). У меня есть интерфейс и некоторые классы реализации. У меня есть один метод в интерфейсе, и у него есть комментарий. в реализующих классах нет комментариев к реализующему методу.

когда это делается в java, javadoc автоматически использует комментарий интерфейса при создании документации. однако теперь, когда я строю свой проект, я получаю предупреждение (переведено со шведского языка, извините) «отсутствует XML-комментарий для видимого типа или члена bla.blabla.blablabla () (cs1591)». это всего лишь предупреждение, так что не все так плохо. но!!! это означает, что xml-файл не был выведен, поэтому я не могу использовать sandcastle для генерации файла документа chm, что является моей настоящей целью ... поиск в коде ошибки ничего не дал: (

мне действительно нужно скопировать комментарий метода ко всем реализующим классам? это как .... дублирование кода D: нет ли способа получить поведение, которое предлагает java?

Answer 1

Я не знаю, как это произошло во время генерации XML-файла, но GhostDoc вполне может спасти вас от выполнения копирования вручную.Я не могу сказать, что использовал его сам.

Я согласен, что это было бы ценно, особенно если документация базового класса (или интерфейса) изменится после того, как производные классы будут реализованыдокументированы.

Answer 2

VSdocman может автоматически разрешать отсутствующие комментарии XML от реализованных интерфейсов при создании документации Более того, подобно GhostDoc, он также может явно копировать унаследованные комментарии в метод реализации. В отличие от Sandcastle, это не бесплатно.

Answer 3

Вы должны скопировать комментарии интерфейсов в реализующий класс. Как правило, это хорошо, так как в идеале два комментария должны быть разными - мое мнение (и практика) по этому поводу можно обобщить следующим образом:

Комментарии к интерфейсу - Объясняет, что метод / свойство / и т. Д. Предполагается / ожидается сделать, но обычно не должно указывать, как должна вести себя любая конкретная реализация

Реализация комментариев класса - Объясняет, что на самом деле делает метод / свойство / и т.д., и может включать некоторые подробности того, как это делается (обычно в <remarks>)

Answer 4

Ну, я не знаю о Java, но извините, вам придется скопировать комментарии интерфейса в реализованный класс. нет встроенного способа сделать это ...

И да, рассмотрите предложение, данное Джонскитом