Каков рекомендуемый способ создания XML-документации для свойства Func?

Каков рекомендуемый способ документирования параметров и возврата свойства Func в классе в С#, например.

public class Test
{
    /// <summary>
    /// A description of what AFunc is for.
    /// </summary>
    /// <remarks>
    /// Should I document the parameters and return here or somewhere else?
    /// </remarks>
    public Func<object, string[], bool> AFunc { get; set; }
}

Intellisense в Visual Studio 2010 не предлагает теги param или return для свойства, как для методов; будут ли эти теги по-прежнему наиболее подходящими для использования?

Редактировать:

После того, как я спросил об этом, я заметил в некоторых xml- документация по msdn, которую можно использовать для пометки любого действительного xml, поэтому сейчас я больше думаю о том, чтобы просто использовать теги param и return; или использовать пользовательские теги и принять решение о соответствующем именовании?


c# properties func xml-documentation
person Alternator    schedule 14.07.2012    source источник

Ответы (2)


arrow_upward
4
arrow_downward

Вместо того, чтобы полагаться на документацию по коду, я бы рекомендовал начать с того, чтобы сделать ваш код более удобным для «конечных разработчиков». Попробуйте изменить тип возвращаемого значения на делегат с понятным именем.

http://msdn.microsoft.com/en-us/library/ms173171(v=vs.100).aspx

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

person Paul Fleming    schedule 14.07.2012
comment
Я думаю, что это на самом деле то, что я после. Но чтобы уточнить, я заменил Func<object, string[], bool> делегатом, который был определен как public delegate bool MyFuncType(object MyFirstParam, string[] MySecondParam). - person Alternator; 15.07.2012

arrow_upward
0
arrow_downward

Свойства не используют param, так как они не принимают параметры — вам нужно использовать typeparam для общих параметров. Вместо returns используйте value.

person Jason Williams    schedule 14.07.2012
comment
Properties don't use param, as they don't take parameters - это правильно, но делегаты делают, и он имеет в виду именно свойство Func tyoe - person Konrad Morawski; 14.07.2012
comment
Он пытается использовать Func‹› в качестве свойства, которое является конкретной реализацией делегата, который всегда возвращает значение, и это ШИРОКОЕ использование. - person kerzek; 14.07.2012
comment
@kerzek, Моравски; Правильный. Судя по ответу Флема выше и другим вещам, которые я прочитал; похоже, что я действительно должен использовать явно определенный делегат и документ против этого определения. - person Alternator; 15.07.2012