Update System.Numerics.Vector<T> documents

[Gnbrkm41]

Summary

• Emphasise that this type is not appropriate for general purpose vector operations
• Update ctor remarks to emphasise only primitive numeric types are allowed
• Update ctor remarks to emphasise only the first Vector<T>.Count elements are added to the vector (for Span/Array overloads)
• Add information about exception that can be thrown when array.Length < Vector<T>.Count

Fixes https://github.com/dotnet/corefx/issues/23448

cc @tannergooding (Issue author, area owner)

[Gnbrkm41]

Looking at some other issues, it's not clear whether the constructors throwing IndexOutOfRangeException is intentional or not: https://github.com/dotnet/corefx/issues/25344

[Gnbrkm41]

https://github.com/dotnet/corefx/issues/25344#issuecomment-541303592

Yes, it is fine to document the current behavior for exception thrown by Vector constructors. Vectorconstructors do not follow the framework design guidelines for performance reasons. Another difference from the standard is that they throw NullReferenceException (vs. the ArgumentNullException recommended by the framework design guidelines).

[Gnbrkm41]

https://github.com/Gnbrkm41/dotnet-api-docs/blob/196c57d8c03853b6d297f7392f04441929264e0e/xml/System.Numerics/Vector%601.xml#L45

https://github.com/Gnbrkm41/dotnet-api-docs/blob/196c57d8c03853b6d297f7392f04441929264e0e/xml/System.Numerics/Vector%601.xml#L55

What should we do for these case, should we use different word instead of 'primitive' here as well?

[carlossanlop]

@tannergooding can you help answer @Gnbrkm41 's question?

[tannergooding]

I think use of the word "primitive" is fine, we just need to ensure that its meaning and/or constraints is defined somewhere

[Gnbrkm41]

I've added some explanations on what we mean when we say "primitive", though I don't think it's a problem anymore given we only have 3 usage of the word "primitive" now.

[Thraka]

I'm not seeing the emphasis about what you said:
- Emphasis that this type is not appropriate for general purpose vector operations

Can you clarify that? So I see that there is this clause:

>It is intended to be used as a building block for vectorizing large algorithms, and therefore cannot be used directly as an arbitrary length vector or tensor.

But that doesn't really tell me to not use it. It says it's intended for X, but code compiles and runs when you use it as a length vector, right? I've used it for an `intpoint` class or a `floatpoint` class, but I don't get the sense of why I'm doing something wrong and what my alternative is.

Scratch what I said above. I was really thinking of Vector2. Does Vector2 fall into this same category of "you shouldn't really use this for everyday normal programming?"

[Gnbrkm41]

Does Vector2 fall into this same category of "you shouldn't really use this for everyday normal programming?"

I don't think it does. Vector2/3/4 are types that represent the mathematical definition of Vector and definitely can be used in places where you need them, like when you represent points on a 2D space 🙂

It's just that Vector can cause confusion that it exists for the same reason (representing mathematical vector) when it's not due to its name and it being in the same System.Numerics namespace, when it really is for vectorisation of algorithms.

[Gnbrkm41]

While I did end up changing the singular to plural with the last commit, I'm actually not entirely sure which one is correct; As a non-native English speaker this is one of those things that I honestly never thought much about, but this made me wonder which is supposed to be used.

Asking around a few people the result I got was to use singular, which contradicts with the suggestion I've got here (which obviously does not help). It would be nice if we could get more opinion or a definitive answer on this...

Apart from that, I probably should additionally state that the Count is a property because it can be confusing to read.

[carlossanlop]

Thank you for working on this, @Gnbrkm41 .
@Thraka has signed off, and the build is passing without warnings.
@tannergooding do the PR looks good to merge?