Question

作为软件开发人员，我想提供我制作的API文档（作为产品的一部分提供），以便我的客户可以有效地使用API而无需在深夜打电话给我。

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

例如，对服务器的请求将得到一个只是数字的结果，而在.NET API中，这将作为枚举结果返回 - 喜欢这个：

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

我的问题是：.NET API文档是否应仅包含枚举成员和描述？ ...还是应该还包括枚举成员的字面值（即服务器发回的内容）？

我可以看到这是一个哲学问题，我不能真正想到C＃中一个引人注目的应用程序，你需要知道枚举成员的字面值。那里有人有例子吗？

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

Answer 1

如果枚举严格来说是C＃而不是我没有理由提供数值。

请注意，与C＃中的C / C ++不同，枚举的基础类型由语言specification明确定义

默认... int ...枚举的已批准类型为byte，sbyte，short，ushort，int，uint，long或ulong。

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

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

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

注意：这是对＃34; .NET API文档是否应仅包含枚举成员和描述的答案？＆＃34;不管实际的C＃代码是否使用数值。

Answer 2

您不必记录C＃代码内部枚举的数值。在这种程度上，我同意@Alexei。

但是，您描述的枚举不是C＃的内部。（它不是你的代码的内部，但这不是重点）。它是网络接口的一部分，将被置于数据报（TCP？IP数据包？）中，Wireshark等网络工具将显示数值，因此应记录。

存储在文件中的数值以及在.NET环境范围之外传播的任何其他枚举也是如此。

.NET API文档是否应定义/公开枚举成员的文字（数值）值？

2 个答案: