FSharp.Core. summary XML documentation for pairwise (List, Array, and Seq) is misleading

[tomcl]

The summary xml documentation for List.pairwise does not explicitly specify the order of the paired elements in the output list, and implies an incorrect order.

From IDE "go to definition" on List.pairwise in a F# project under using FSharp.Core 8.0.200:

///<summary>Returns a list of each element in the input list and its predecessor, with the
/// exception of the first element which is only returned as the predecessor of the second element.</summary>
///<param name="list">The input list.</param>
///<returns>The result list.</returns>
///<example id="pairwise-1"><code lang="fsharp">
/// let inputs = [1; 2; 3; 4]
///
/// inputs |&gt; List.pairwise
/// </code>
/// Evaluates to <c>[(1, 2); (2, 3); (3, 4)]</c>.
/// </example>
[<CompiledName ("Pairwise")>]
val pairwise: list: 'T list -> ('T * 'T) list

** Suggested change **

///<summary>Returns a list of each element in the input list paired with its predecessor, with the
/// exception of the first element which is only returned as the predecessor of the second element.
/// The predecessor comes first in the returned pairs.</summary>
///<param name="list">The input list.</param>
///<returns>The result list.</returns>
///<example id="pairwise-1"><code lang="fsharp">
/// let inputs = [1; 2; 3; 4]
///
/// inputs |&gt; List.pairwise
/// </code>
/// Evaluates to <c>[(1, 2); (2, 3); (3, 4)]</c>.
/// </example>
[<CompiledName ("Pairwise")>]
val pairwise: list: 'T list -> ('T * 'T) list

Versions

(I think this has been constant forever and is not version dependent)

• FSharp.Core 8.0.0.0
• Released as FSharp.Core dll 8.0.200

Related information

The example in the documentation is correct. However when programming the summary XML documentation is more important because easily available through IDEs. This is a function where the order of the elements in the returned pair is not obvious and will not be easily remembered - so accurate summary documentation is especially helpful.