10

With ValueTuple in C# 7, it is now possible to write methods and properties that return or consume composite objects without explicitly declaring a type. These named tuples can however be potentially confusing when no documentation is provided.

As the primary and probably most convenient way of documenting libraries is by using XML documentation, is there any way using XML documentation to provide a description of the variables in a named tuple?

I know the obvious solution is to declare a type and document it accordingly. However, granted that due to some 'reasons' that cannot be done, is it possible to XML document the data members in a ValueTuple?

NB: A similar question was asked before the advent of the ValueTuple.

Alex Essilfie
  • 12,339
  • 9
  • 70
  • 108
  • You are trying to use ValueTuple as if it were a record. Tuple (value or classic) fields don't have specific names, the field names you see are compiler magic. There's no type on which to specify XML documentation. Tuples represent complex return *values*, not composite objects. – Panagiotis Kanavos May 07 '18 at 14:15
  • 1
    @PanagiotisKanavos Yes, thanks for repeating everything I know already. Going by your comment, one could conclude that tuples are only meant to be consumed internally. However there are specific cases where tuples are best suited for the job (e.g. `TryCast()`, `Dictionary.TryGetValue()`). My question is about how to document tuples in those cases where using tuples is more expedient than predefined or one's own types. – Alex Essilfie May 07 '18 at 21:22
  • The implications of what you understand already is that you can't apply documentation comments to specific tuple instantiations. No more than you can apply them to a `List` vs a `List`. It's not even possible in C# to specify a type alias for a tuple, hence there's no construct to which one can apply that documentation. – Panagiotis Kanavos May 08 '18 at 07:27
  • The situation is more or less the same in F# which had tuples since v1. Tuples are never meant to return composite objects even there, which is why you can't name fields, or define specific tuple types. At least you can specify *aliases* but the real type is still a nameless tuple. In F# composite value-like objects are represented by *records*. Unfortunately, records aren't available in C# yet – Panagiotis Kanavos May 08 '18 at 07:36

1 Answers1

10

C# has no special syntax for documenting named elements of a tuple, you will have to use the normal <returns> and <param> elements and explain in words what each named element contains.

Though there is a proposal for adding this capability to the language.

svick
  • 236,525
  • 50
  • 385
  • 514