Использование атрибутов C # и документации - PullRequest
Новая
       36

Использование атрибутов C # и документации

2 голосов
/ 23 августа 2011

Рассмотрим следующий исходный код. 

/// <summary>
/// This is a method I would like to document
/// </summary>
/// <param name="param1">Description for param1</param>
/// <param name="param2">Description for param2</param>
/// <returns>See Type1</returns>
[Api(1)]
public Type1 Method1(
    [ApiParam(Name = Names.Name1, IsRequired = true)] string param1
     string param2
    ) {
    ...
    }

/// <summary>
/// This is a method I would like NOT to document
/// </summary>
public void Method2() {
    ...
    }

Мой вопрос заключается в том, как вы, ребята, справляетесь с тем фактом, что код часто использует атрибуты C #, но инструменты генерации документации, похоже, не поддерживают их.

В приведенном выше примере я хотел бы сгенерировать файл (ы) помощи, который будет включать только методы (и типы), помеченные атрибутом ApiAttribute. Например.

Например, для Doxygen решение использует отдельные физические папки.

1 Ответ

2 голосов
/ 23 августа 2011

Атрибуты должны использоваться в качестве декоратора метаданных (и в некоторых случаях добавлять функциональность к определенным частям кода), и они не должны принимать решения по документации;для этого и нужна документация.Если у вас есть библиотека, предоставляющая API, вы должны использовать классы фасада для самого API, который может (и, вероятно, должен) находиться в другой папке.Создайте документ из этой папки, и все готово.Кроме того, это избавит вас от головной боли, разделив проблемы.

...