coreclr: Automatic port of triple slash from System

[carlossanlop]

Fixed a bug in the porting tool and found additional coreclr comments that could be automatically ported from this area.
Not sure who's the proper owner of these APIs, but the comments are simple enough and I tried to correct them as much as possible.
Adding @mairaw @rpetrusha for language review.

[carlossanlop]

This remark was a bit difficult to understand, especially the 3rd sentence, so I left it untouched. Can I get some help to properly rewrite it?
There's another similar remark in another API in this same PR.

[carlossanlop]

Ok I gave it a try. Hopefully it looks a bit better.

[rpetrusha]

I still don't think it's clear. There's nothing that ties length to the length of a collection. And the source ignores the length argument if the index is from the start and just returns the original index:

        public int GetOffset(int length)
        {
            int offset = _value;
            if (IsFromEnd)
            {
                // offset = length - (~value)
                // offset = length + (~(~value) + 1)
                // offset = length + value + 1
 
                offset += length + 1;
            }
            return offset;
        }

[carlossanlop]

Help us, @tarekgh, you're our only hope.
Can you help clarify this remark?

[carlossanlop]

What I understood from Tarek's explanation is that length is only considered when retrieving the offset from the end. You are correct, the method ignores the length if it's from the start.

[carlossanlop]

I removed the System.GC* APIs from this PR and moved them to their own PR: #2759

I added two extra files I found in System: SequencePosition and AggregateException.

[rpetrusha]

I've reviewed this up to the Range.Equals method, @carlossanlop. I'll continue the review tomorrow.

[rpetrusha]

I've finished reviewing this PR, @carlossanlop. I realize that I created suggestions for the first set of types rather than editing the documentation directly. (I also did that from String because I could never load the file successfully in my browser.) For the remaining types, I made changes directly in the document, so please review them.

[carlossanlop]

@tarekgh it seems you added the GetOffset function for Index. Would you mind helping us clarify the remark that you wrote for that method?

[carlossanlop]

@rpetrusha I can't commit your suggestions in a batch. Can I ask you a favor? Can you please try it yourself? I am getting an error saying "the diff has changed" whenever I try to commit the batch.
I was merging all of them except the one where I left a question for Tarek.

Edit:

Nevermind. I figured out the root cause: The String.xml file is so large (14433 lines!) that GitHub is unable to merge suggestions directly here, which is why I was seeing the error "the diff has changed".

I had to merge each file's suggestions individually to find the root cause, then merge the String.xml changes via my enlistment.

Anyway, problem solved!

[carlossanlop]

@rpetrusha I addressed the last comments based on Tarek's explanation of Index.GetOffset. Can you please take a look in case it still needs some more rewording? I am hoping it's clearer now.

[rpetrusha]

I've made some minor changes, and the GetOffset method still is not clear, but this is ready to merge once the build completes successfully, @carlossanlop

[carlossanlop]

Do you mind if we open a separate issue to review the GetOffset documentation? @rpetrusha

[rpetrusha]

No, a separate PR is fine, @carlossanlop. It would be good to get this merged -- although it never seems to build successfully...