Should an .NET API documentation define/expose the literal (numerical) value of enum members? [closed]

Question

Closed. This question is opinion-based. It is not currently accepting answers.

---

Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.

Closed 5 years ago.

Improve this question

As a Software Developer I want to provide documentation for an API I made (provided as part of a product) so that my customers can effectively use the API without having to call me late at night.

This API is provided in various forms, including a .NET assembly. The .NET assembly includes enums for outputs (specifically return codes). I see some previous discussion about the merits of this approach: Should enum never be used in an API? ... so I'll continue.

For example a request to the server will get a result which is just a number, and in the .NET API this will be returned as a enumerated result - something like this:

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

My question is: Should a .NET API document include the enum member and description only? ... or should it also include the literal value of the enum member as well (i.e. what the server sent back)?

I can see this is something of a philosophical question, and I cannot really think of a compelling application in C# where you need to know the literal value of an enum member. Does anyone out there have an example?

Finally I would add we also provide equivalent APIs including OLE/COM where enum members are documented including their literal numerical values.

Answer 1

You don't have to document the numeric values of enumerations internal to the C# code. To that extent, I agree with @Alexei.

However, the enumeration you describe is not internal to C#. (It's not internal to your code either, but that's not the important point). It is part of a network interface, and will be placed into datagrams (TCP?IP packets?) Network tools such as Wireshark will show the numeric value, so you should document it.

The same would be true of numeric values stored in files, and any other enumeration which travels outside the confines of the .NET environment.

Answer 2

If enum is strictly C# than I see no good reason to provide numerical values.

Note that unlike C/C++ in C# underlying type of the enum is well defined by language specification

default ...int ... The approved types for an enum are byte, sbyte, short, ushort, int, uint, long, or ulong.

Following are reasons why you may need to add numerical values (mainly interoperation with other languages):

• enum is set of flags used to describe file or wire format - you don't know what language caller would use so enum may not be available
• API can be used in language that does not support enums or have different way to map names to values
• you rely on some particular values of enums rather than names (hiding such behavior from public API may be better, but sometimes not avoidable).

Note that you need to be very careful with versioning of your enum when creating next version of API - as any constant value may be inlined into code at compile time in the calling code.

Note: This is answer to "Should a .NET API documentation include the enum member and description only?" irrespective if actual C# code uses numeric values or not.