Должна ли документация .NET API определять/раскрывать буквальное (числовое) значение членов перечисления? [закрыто] ⇐ C#

[Anonymous]

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

Этот API предоставляется в различных формах, включая сборку .NET. Сборка .NET включает перечисления для выходных данных (в частности, коды возврата). Я вижу предыдущее обсуждение достоинств этого подхода: следует ли никогда не использовать enum в API? ... так что я продолжу.

Например, запрос к серверу вернет результат, который представляет собой просто число, а в .NET API это будет возвращается как перечисляемый результат — что-то вроде этого:

Код: Выделить всё

public enum ApiResult {
/// 
/// Success
/// 
Ok,
/// 
/// Input parameter was incorrect
/// 
InvalidParameter,
/// 
/// The method failed
/// 
OperationFailed
}

Мой вопрос: должен ли документ .NET API включать только член перечисления и описание? ... или оно также должно включать буквальное значение члена перечисления (т. е. то, что сервер отправил обратно)?

Я вижу, что это что-то вроде философского вопрос, и я не могу придумать убедительного приложения на C#, где вам нужно знать буквальное значение члена перечисления. Есть ли у кого-нибудь пример?

Наконец, я хотел бы добавить, что мы также предоставляем эквивалентные API, включая OLE/COM, где члены перечисления документируются, включая их буквальные числовые значения.

Подробнее здесь: https://stackoverflow.com/questions/227 ... l-value-of