СУХОЙ в C # документации кода на два варианта интерфейса - PullRequest
Новая
       17

СУХОЙ в C # документации кода на два варианта интерфейса

1 голос
/ 27 марта 2012

В настоящее время я переписываю SDK для доступа к веб-сервису.

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

Так что вместо 

new Query(
 Age = new AgeFilter() { From = 18, To = 65 },
 Location = new PostalCodeFilter() { Zip = 12345, new RadiusDefinition() { ... } }
);

пользователь теперь может написать: 

Query.Create()
  .WithAge(18, 65)
  .WithLocation(12345, 50, "miles");

Теперь я обнаружил, что традиционный способ также должен быть включен (я не могу скрыть реальные объекты как внутренние).

Как мне избежать документирования как параметров интерфейса, так и полей классов данных? Описания одинаковы. Я думал о see / seealso, но в Visual Studio Code Assistant это не будет отображаться.

Ответы [ 2 ]

1 голос
/ 27 марта 2012

Если вы используете Sandcastle, вы можете использовать тег <inheritdoc /> так: 

///<param name="from">
///<inheritdoc cref="AgeFilter.From" select="/summary/node()" />
///</param>

или 

///<summary>
///<inheritdoc cref="QueryFilters.WithAge" select="/param[@name='from']/node()"/>
///</summary>
1 голос
/ 27 марта 2012

Не думаю, что ты можешь. Комментарий в формате xml-doc применяется к очень специфической вещи, и ее нелегко «разделить». Но вы можете «связать» между элементами, используя тег <see>. Посмотрите на http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx и посмотрите, пригодится ли он вам.

Поймите, что DRY действительно применяется в основном к коду; написание одной и той же строки кода дважды означает, что если необходимо внести изменения в логику, присущую этому коду, то это необходимо сделать дважды. То, что вы пытаетесь избежать повторения, - это разметка, которая, хотя и может иметь одну и ту же внутреннюю проблему необходимости вносить изменения в нескольких местах, в разметке обычно доступно меньше инструментов, чтобы избежать повторения подобных вещей. Если вы посмотрите на другие библиотеки, у которых есть несколько способов достижения аналогичной цели, вы обнаружите, что большая часть документации выглядит скопированной.

...