Как документировать свойство класса

Question

Каков правильный синтаксис комментария XML для свойства класса?

Answer 1

Установите это: http://submain.com/products/ghostdoc.aspx

Щелкните правой кнопкой мыши на свойстве, выберите 'Документ' Это. Заполните пробелы.

Answer 2

Согласно MSDN, link, похоже, что для свойств класса нет официального тега. Но, я хотел бы использовать что-то вроде этого:

/// <summary>Here is an example of a propertylist: 
/// <list type="Properties"> 
/// <item> 
/// <description>Property 1.</description> 
/// </item> 
/// <item> 
/// <description>Property 2.</description> 
/// </item> 
/// </list> 
/// </summary> 

Answer 3

Я хотел бы предложить использовать StyleCop. Он не только принуждает вас (немного к сильному для моего вкуса) комментировать, но также дает вам подсказку о том, как следует начинать комментарии.

Answer 4

В ответ на запрос явных примеров, следующий экстракт из StyleCop помощи документа «SA1623: PropertySummaryDocumentationMustMatchAccessors»:

резюме текст в зонах должен начинаться с формулировкой описания типов аксессоров подвергается в пределах имущество. Если свойство содержит только элемент доступа get, сводка должна начинаться со слова «Gets». Если свойство содержит только элемент доступа к набору, сводка должна начинаться со слова «Sets». Если свойство раскрывает как get, так и set accessor, сводный текст должен начинаться с «Gets or sets».

Например, рассмотрим следующее свойство, которое предоставляет как get, так и set accessor. Сводный текст начинается со слов «Gets or sets».

/// <summary> 
/// Gets or sets the name of the customer. 
/// </summary> 
public string Name 
{ 
    get { return this.name; } 
    set { this.name = value; } 
} 

Если свойство возвращает булево значение, применяется дополнительное правило. Сводный текст для свойств Boolean должен содержать слова «Возвращает значение, указывающее, есть ли», «Устанавливает значение, указывающее, является ли», или «Получает или задает значение, указывающее, есть ли». Например, рассмотрим следующее логическое свойство, которое только выставляет ПОЛУЧИТЬ аксессор:

/// <summary> 
/// Gets a value indicating whether the item is enabled. 
/// </summary> 
public bool Enabled 
{ 
    get { return this.enabled; } 
} 

В некоторых ситуациях, множество сбруя для свойства могут иметь более ограниченный доступ, чем ГЭТ аксессору. Например:

/// <summary> 
/// Gets the name of the customer. 
/// </summary> 
public string Name 
{ 
    get { return this.name; } 
    private set { this.name = value; } 
} 

В этом примере множество аксессор был дан частный доступ, а это означает, что она может быть доступна только местными членами класса, в котором он содержится. Однако получатель доступа наследует свой доступ от родительского свойства, таким образом, к нему может обращаться любой вызывающий объект, поскольку свойство имеет открытый доступ.

В этом случае в сводном тексте документации следует избегать обращения к устройству доступа, поскольку оно не отображается внешним абонентам.

StyleCop применяет ряд правил, чтобы определить, когда в ассемблерной документации свойства указывается ссылка на аксессуар. В общем, эти правила требуют, чтобы привязанный доступ к объекту был привязан, когда он видим одному и тому же набору вызывающих абонентов, таких как get accessor, или когда он видим для внешних классов или наследует классы.

Конкретные правила для определения, следует ли включать множество аксессор в итоговой документации отеля являются:

1.Аксессуар набора имеет тот же уровень доступа, что и получатель доступа. Например:

/// <summary> 
/// Gets or sets the name of the customer. 
/// </summary> 
protected string Name 
{ 
    get { return this.name; } 
    set { this.name = value; } 
} 

2.Интерьер является внутренне доступным только внутри сборки, а доступный аксессуар также имеет внутренний доступ. Например:

internal class Class1 
{ 
    /// <summary> 
    /// Gets or sets the name of the customer. 
    /// </summary> 
    protected string Name 
    { 
     get { return this.name; } 
     internal set { this.name = value; } 
    } 
} 

internal class Class1 
{ 
    public class Class2 
    { 
     /// <summary> 
     /// Gets or sets the name of the customer. 
     /// </summary> 
     public string Name 
     { 
      get { return this.name; } 
      internal set { this.name = value; } 
     } 
    } 
} 

3. свойство является частным или содержится под частным классом, а множество аксессор имеет любой модификатор доступа, кроме частных. В приведенном ниже примере модификатор доступа, объявленный в установленном аксессуре, не имеет смысла, поскольку набор доступа содержит закрытый класс и, следовательно, не может быть замечен другими классами вне класса 1. Это фактически дает установленному аксессуару тот же уровень доступа, что и get accessor.

public class Class1 
{ 
    private class Class2 
    { 
     public class Class3 
     { 
      /// <summary> 
      /// Gets or sets the name of the customer. 
      /// </summary> 
      public string Name 
      { 
       get { return this.name; } 
       internal set { this.name = value; } 
      } 
     } 
    } 
} 

4. При условии, что доступный аксессуар не имеет защищенного или защищенного внутреннего доступа, на него должно быть указано в документации. Защищенный или защищенный доступ к внутреннему набору всегда можно увидеть классом, наследующим класс, содержащий свойство.

internal class Class1 
{ 
    public class Class2 
    { 
     /// <summary> 
     /// Gets or sets the name of the customer. 
     /// </summary> 
     internal string Name 
     { 
      get { return this.name; } 
      protected set { this.name = value; } 
     } 
    } 

    private class Class3 : Class2 
    { 
     public Class3(string name) { this.Name = name; } 
    } 
}