C# .NETAPI文档是否应该定义/公开枚举成员的文字（数字）值？

作为一名软件开发人员，我希望为我制作的API（作为产品的一部分提供）提供文档，以便我的客户能够有效地使用API，而不必在深夜给我打电话

此API以各种形式提供，包括.NET程序集。NET程序集包括输出的枚举（特别是返回代码）。我看到以前关于这种方法优点的一些讨论：。。。所以我会继续

例如，对服务器的请求将得到一个仅为一个数字的结果，在.NET API中，该结果将作为枚举结果返回-类似于以下内容：

public枚举结果{
/// 
///成功
/// 
好啊
/// 
///输入参数不正确
/// 
无效参数，
/// 
///该方法失败
/// 
操作失败
}

我的问题是：.NETAPI文档是否应该只包含枚举成员和描述。。。或者它还应该包括枚举成员的文本值（即服务器返回的内容）

我可以看出这是一个哲学问题，我想不出在C#中有什么引人注目的应用程序需要知道枚举成员的字面值。有没有人举个例子

最后我要补充的是，我们还提供了等效的API，包括OLE/COM，其中记录了枚举成员，包括它们的文字数字值。

如果枚举严格为C，那么我看不到提供数字值的好理由

注意，和C中的C/C++不同，枚举的底层类型是由语言很好地定义的

默认值…

int

。。。批准的枚举类型有byte、sbyte、short、ushort、int、uint、long或ulong

以下是您可能需要添加数值的原因（主要是与其他语言的互操作）：

• enum是一组用于描述文件或导线格式的标志-您不知道调用方将使用何种语言，因此enum可能不可用
• API可以用在不支持枚举的语言中，或者用不同的方法将名称映射到值
• 您依赖于枚举的某些特定值而不是名称（对公共API隐藏此类行为可能更好，但有时无法避免）

请注意，在创建下一版本的API时，您需要非常小心地对枚举进行版本控制，因为任何常量值都可能在调用代码的编译时内联到代码中

---

注意：这是对“一个.NET API文档是否应该只包含枚举成员和描述？”的回答，不管实际的C#代码是否使用数值。

您不必记录C#代码内部枚举的数值。在这一点上，我同意@Alexei

但是，您描述的枚举不是C#的内部枚举。（它也不是代码内部的，但这不是重点）。它是网络接口的一部分，将被放入数据报（TCP？IP数据包？）中。Wireshark等网络工具将显示数值，因此您应该对其进行记录

---

存储在文件中的数值和任何其他超出.NET环境限制的枚举也是如此。

我经常显式设置（“提供”）值，即使我没有“公开”这样的值-API协定仍然通过枚举，而不是直接通过数值。我喜欢提供显式值的一个原因是，以后添加的代码不会意外更改指定的值（即使它们是自动指定的），不，从“转到定义”命令中已经很明显了。一般来说，如果你不喜欢别人在不方便的时候给你打电话，那就告诉他们电话的来源。一定要把他们给你的bug修复整合到主干中。谢谢你的输入-我同意这些都是定义特定值的好理由。倾向于支持我的立场-对于C#本身，没有令人信服的理由，但对于互操作性或外部接口，数值可能有用。@user2864740-我想你的评论是关于其他东西的。。。问题是“一个.NETAPI文档是否应该只包含枚举成员和描述”-我不知道在文档中如何区分“提供”和“公开”。API文档中是否存在数字值（无论C#code是如何编写的）…我认为最后一条评论中的观点，以及在答案末尾编辑的观点，应该更加突出/集中，因为它比当前的介绍性陈述更强烈（并且与之不同）@user2864740-上面有一个编辑按钮：）-我对现在的情况很满意。。。请随意更改答案。

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