Skip to content

Fix git push error for protected CLA branch - #2234

Merged
Colin Robertson (colin-home) merged 57 commits into
masterfrom
master637263955026892530
Jun 1, 2020
Merged

Colin Robertson (colin-home) merged 57 commits into
masterfrom
master637263955026892530

Conversation

@opbld15

@opbld15 opbld15 commented May 30, 2020

Copy link
Copy Markdown
Contributor

The pull request is created from master637263955026892530 to master to fix git push error for protected CLA branch

Tyler Whitney and others added 30 commits April 20, 2020 20:33
* Monospace `vector` and `array`, being the names of Standard containers.
* `void main()` is non-Standard; it should be `int main()`. (There's a special rule that `return 0;` is unnecessary here.)
* Qualify `std::cout`, otherwise the example won't compile. (There are still no spaces or newlines being printed after each element.)
* Mention `/std:c++latest` as a requirement.
* Suggestion: mention built-in arrays, `std::array`, and `std::vector` as examples of contiguous storage. May be helpful for readers who don't immediately recognize "contiguous" or "back-to-back". Feel free to discard.
* "indexed by the size of the objects" is unclear - it's talking about indexing from `[0, N)` but at first it sounds like it might be talking about `sizeof(Object)`. Suggestion: simply say "using a pointer and an index".
* "part of the template declaration" isn't the right terminology. The Standard Library contains the declaration (and definition) of `std::span`. The user provides template arguments to `span` when they say `span<int, 5>`.
* `dynamic-size` is nonexistent; replace with `dynamic_extent`.
* Suggestion: Rephrase the descriptions of `const_pointer` and `const_reference` to make it clear where the constness applies.
* FIXME: `operator[]` is mentioned in the table twice, as an accessor and an operator. I added a FIXME note but don't know how to resolve this.
* Monospace `array` and `vector`.
* Replace a smart quote with a plain quote.
* Mention `/std:c++latest` as a requirement.
* Add FIXME notes to examples (didn't attempt to fix all examples)
* Missing semicolon in the declaration of `begin()`.
* `data()` said: "If the span is empty, returns `nullptr`." This is incorrect, so I've removed the sentence. The truth is complicated: a default-constructed span indeed has null `data` and zero `size`. However, it's possible for an empty (zero `size`) span to have non-null `data`; this can be manually constructed, or obtained from `subspan`. This seems weird, but it can be meaningful to have a span denoting a location but zero elements. For example, the `equal_range` algorithm returns a sub-range of equivalent elements in a range; if there are no such elements, it returns an empty subrange located where such elements could be inserted while preserving the ordering. I am unsure how to explain this behavior of `data` briefly. 
* Removed apparently-spurious `difference_type` link right before that section; apologies if I misunderstood what was happening there.
* Fixed typoed and incorrect `difference_type` example - it was subtracting the `int` elements. Instead, `difference_type` is the result of subtracting iterators. Attempted to correct example; haven't actually verified that this compiles (modulo std/void issues).
* Added missing semicolon to `empty` declaration.
* Added missing `noexcept` to `end` declaration (present for `begin`).
* NO CHANGE MADE: `end` talks about "the sentinel" but I am unsure whether this is good terminology. I usually speak of a sentinel node in node-based containers (because such a node physically exists), but for contiguous containers like `vector`, I speak of a "past-the-end location". This is possibly more important for `span` because `span` isn't placing anything special there.
* Remove top-level `const` from `first(size_type count)`'s parameter - this has meaning only to implementers, not to callers.
* Fix `front` example which was calling `first`.
* Don't specify `iterator` as `_Span_iterator<T>`, which is an STL-internal type. I've replaced this with `implementation-defined-iterator-type` (the Standard just says `implementation-defined`).
* Remove `const` from `operator[]`'s parameter. Mark the member function as `const`. Add a semicolon.
* Remove unused (copy-pasted?) `auto i` variable from `operator[]` example.
* FIXME NOTE: The `operator=` example depicts copy-initialization, not copy assignment. Just noted, haven't fixed.
* FIXME NOTE: Also commented for-loop in that example
* Add `noexcept` to `rend` (already present on `rbegin`).
* Replaced incorrect `size_type` description.
* Fixed misleading `size_type` example - it is meant to be used with `size` calculations, not `sizeof` (although it is ultimately `size_t`, the same type).
* FIXME NOTE: `dynamicExtent` in span constructors should be `dynamic_extent`; noted but not fixed.
* ASK CASEY: The `requires` depicted for the `span()` default ctor appears to be incorrectly positioned but I don't really understand concept syntax yet.
* Fix `template <It>` and `template <It, End>` which are not valid syntax.
* Fix `span(It first, End last)` description - it referred to `end` but the variable's name is `last`.
* FIXME: The `subspan` signature had a missing part of a conditional expression; noted as FIXME.
* `subspan` `count` was described as "from the end this span" which is damaged and appears to be copy-pasted from `last`. I believe removing this fixes the description.
* `subspan` `count` also said "If span is `dynamic_extent`" which was a typo; fixed.
* FIXME NOTE: The example prints `subspan<1>` but calls `subspan(1)`. It's unclear to me whether you meant to depict both the 1-function-argument and 1-template-argument forms.
* Removed duplicated `subspan` signature.
* NOT FIXED: `subspan` has a declaration repeatedly mentioning `size_t`. All occurrences of `size_t` in this page should be audited to see whether they should be `size_type` (likely).
* Deduction guides mentioned the STL-internal macro `_RANGES`; replaced with `ranges::` as `std::` appears to be assumed here.
Tyler Whitney (TylerMSFT) and others added 26 commits May 23, 2020 08:12
The other correction may not be needed - I'd proposed adding the template parameters to the Parameters section of the `span::span` constructors.
* start draft

* draft

* draft

* draft

* draft

* draft

* draft

* remove my bookmarks

* fix typos

* fix build warnings

* acrolinx and link fixes

* draft

* draft

* typos

* add top- links

* mark code headings as code so they don't get localized

* Update span.md

* Monospace `vector` and `array`, being the names of Standard containers.
* `void main()` is non-Standard; it should be `int main()`. (There's a special rule that `return 0;` is unnecessary here.)
* Qualify `std::cout`, otherwise the example won't compile. (There are still no spaces or newlines being printed after each element.)
* Mention `/std:c++latest` as a requirement.

* Update span-class.md

* Suggestion: mention built-in arrays, `std::array`, and `std::vector` as examples of contiguous storage. May be helpful for readers who don't immediately recognize "contiguous" or "back-to-back". Feel free to discard.
* "indexed by the size of the objects" is unclear - it's talking about indexing from `[0, N)` but at first it sounds like it might be talking about `sizeof(Object)`. Suggestion: simply say "using a pointer and an index".
* "part of the template declaration" isn't the right terminology. The Standard Library contains the declaration (and definition) of `std::span`. The user provides template arguments to `span` when they say `span<int, 5>`.
* `dynamic-size` is nonexistent; replace with `dynamic_extent`.
* Suggestion: Rephrase the descriptions of `const_pointer` and `const_reference` to make it clear where the constness applies.
* FIXME: `operator[]` is mentioned in the table twice, as an accessor and an operator. I added a FIXME  but don't know how to resolve this.
* Monospace `array` and `vector`.
* Replace a smart quote with a plain quote.
* Mention `/std:c++latest` as a requirement.
* Add FIXME notes to examples (didn't attempt to fix all examples)
* Missing semicolon in the declaration of `begin()`.
* `data()` said: "If the span is empty, returns `nullptr`." This is incorrect, so I've removed the sentence. The truth is complicated: a default-constructed span indeed has null `data` and zero `size`. However, it's possible for an empty (zero `size`) span to have non-null `data`; this can be manually constructed, or obtained from `subspan`. This seems weird, but it can be meaningful to have a span denoting a location but zero elements. For example, the `equal_range` algorithm returns a sub-range of equivalent elements in a range; if there are no such elements, it returns an empty subrange located where such elements could be inserted while preserving the ordering. I am unsure how to explain this behavior of `data` briefly. 
* Removed apparently-spurious `difference_type` link right before that section; apologies if I misunderstood what was happening there.
* Fixed typoed and incorrect `difference_type` example - it was subtracting the `int` elements. Instead, `difference_type` is the result of subtracting iterators. Attempted to correct example; haven't actually verified that this compiles (modulo std/void issues).
* Added missing semicolon to `empty` declaration.
* Added missing `noexcept` to `end` declaration (present for `begin`).
* NO CHANGE MADE: `end` talks about "the sentinel" but I am unsure whether this is good terminology. I usually speak of a sentinel node in node-based containers (because such a node physically exists), but for contiguous containers like `vector`, I speak of a "past-the-end location". This is possibly more  for `span` because `span` isn't placing anything special there.
* Remove top- `const` from `first(size_type count)`'s parameter - this has meaning only to implementers, not to callers.
* Fix `front` example which was calling `first`.
* Don't specify `iterator` as `_Span_iterator<T>`, which is an STL-internal type. I've replaced this with `implementation-defined-iterator-type` (the Standard just says `implementation-defined`).
* Remove `const` from `operator[]`'s parameter. Mark the member function as `const`. Add a semicolon.
* Remove unused (copy-pasted?) `auto i` variable from `operator[]` example.
* FIXME : The `operator=` example depicts copy-initialization, not copy assignment. Just noted, haven't fixed.
* FIXME NOTE: Also commented for-loop in that example
* Add `noexcept` to `rend` (already present on `rbegin`).
* Replaced incorrect `size_type` description.
* Fixed misleading `size_type` example - it is meant to be used with `size` calculations, not `sizeof` (although it is ultimately `size_t`, the same type).
* FIXME NOTE: `dynamicExtent` in span constructors should be `dynamic_extent`; noted but not fixed.
* ASK CASEY: The `requires` depicted for the `span()` default ctor appears to be incorrectly positioned but I don't really understand concept syntax yet.
* Fix `template <It>` and `template <It, End>` which are not valid syntax.
* Fix `span(It first, End last)` description - it referred to `end` but the variable's name is `last`.
* FIXME: The `subspan` signature had a missing part of a conditional expression; noted as FIXME.
* `subspan` `count` was described as "from the end this span" which is damaged and appears to be copy-pasted from `last`. I believe removing this fixes the description.
* `subspan` `count` also said "If span is `dynamic_extent`" which was a typo; fixed.
* FIXME NOTE: The example prints `subspan<1>` but calls `subspan(1)`. It's unclear to me whether you meant to depict both the 1-function-argument and 1-template-argument forms.
* Removed duplicated `subspan` signature.
* NOT FIXED: `subspan` has a declaration repeatedly mentioning `size_t`. All occurrences of `size_t` in this page should be audited to see whether they should be `size_type` (likely).
* Deduction guides mentioned the STL-internal macro `_RANGES`; replaced with `ranges::` as `std::` appears to be assumed .

* Update span-functions.md

* Rename parameter from `span` to `s` to avoid "shadowing" ambiguity. (The Standard says `s` .)
* Add semicolons to declarations.
* Fix `Dynamic_Extent` capitalization to `dynamic_extent`.
* FIXME NOTES: The claimed return types are incorrect; these functions return `span<const byte, MEOW>` and `span<byte, MEOW>` where `MEOW` is a conditional expression. Noted but not fixed.
* RENAMED: The Standard name of the function is `as_writable_bytes`, not `writeable`. I've replaced all occurrences in this document; please check any cross-references. (This was renamed during Standardization, so old mentions may be common. We never shipped the old name in the STL.)

* incorp tech review

* incorp tech review

* remove nullptr info

* update ms.date

* fix backtick

* a little wordsmithing

* Fix template name

The other correction may not be needed - I'd proposed adding the template parameters to the Parameters section of the `span::span` constructors.

Co-authored-by: Tyler Whitney <Tyler.Whitney@microsoft.com>
Co-authored-by: Stephan T. Lavavej <stl@microsoft.com>
Co-authored-by: Colin Robertson <corob@microsoft.com>
Confirm merge from FromPublicMasterBranch to master to sync with https://github.com/MicrosoftDocs/cpp-docs (branch master)
Fix an organization issue in Linux docs per 2231
@colin-home
Colin Robertson (colin-home) deleted the master637263955026892530 branch June 1, 2020 03:19
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

Development

Successfully merging this pull request may close these issues.

5 participants