Unclear verbiage

[KatDevsGames]

Type of issue

Typo

Description

The verbiage "A 32-bit integer that represents the index in array at which copying begins." is extremely unclear/unhelpful.

It only says it is the initial index value when the copy operation begins. It doesn't say if it is the source's index or destination's index. Wording should be clarified.

Page URL

https://learn.microsoft.com/en-us/dotnet/api/system.array.copyto?view=net-8.0#system-array-copyto(system-array-system-int32)

Content source URL

https://github.com/dotnet/dotnet-api-docs/blob/main/xml/System/Array.xml

Document Version Independent Id

60447b8e-6071-b21e-2dfe-e3013ed84225

Article author

@dotnet-bot

[dotnet-policy-service]

Tagging subscribers to this area: @dotnet/area-system-runtime

[tannergooding]

It only says it is the initial index value when the copy operation begins. It doesn't say if it is the source's index or destination's index. Wording should be clarified.

I agree this is a little bit confusing, but there's also not necessarily an easy fix here. For better or worse the signature is CopyTo(Array array, long index) and the actual XML documentation comment is:

A 32-bit integer that represents the index in array at which copying begins.

or to make it more visible

<param name="index">A 32-bit integer that represents the index in <paramref name="array" /> at which copying begins.</param>

This is "supposed" to be made apparent in the UI by the difference in highlighting for the text

While this isn't made visible at all in the IDE:

---

CC. @gewarren for suggestions on fixes.

We of course can't go and change the name of the parameter to be something more clear like destinationArray, as that is a source breaking change. Perhaps we can insert additional wording or here to make it more clear we're talking about the parameter named array, particularly as that will also improve the experience for the IDE and for people who use screen readers or other tools to make documentation more accessible.

[gewarren]

I made some improvements in #10830.

While this isn't made visible at all in the IDE

That seems like a bug to me. Or at least a poor design choice. There is some wording that sort of relies on the fact that the reader knows it's referencing a parameter name - for example, the reference to the count parameter in this summary:

Assigns the given value to the elements of the specified <paramref name="array" /> that are within the range of <paramref name="startIndex" /> (inclusive) and the next <paramref name="count" /> number of indices.