docs: fix some typos and confusing wording #976
Merged
Conversation
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
gregmarr
reviewed
Feb 14, 2024
docs/index.md
Outdated
| @@ -152,7 +152,7 @@ Here we can see more of how Cpp2 makes it features work. | |||
| **How: Simple and safe by default.** | |||
|
|
|||
| - **Line 9:** CTAD just works, because it turns into ordinary C++ code which is CTAD-aware. | |||
| - **Lines 10-11:** The accesses of `words[0]` and `words[1]` are bounds-checked nonintrusively at the call site by default. Because it's nonintrusive, it works seamlessly with all existing container types that are `std::ssize`-aware, when you use them from safe Cpp2 code. | |||
There was a problem hiding this comment.
This is not a typo. https://en.cppreference.com/w/cpp/iterator/size
There was a problem hiding this comment.
I know, but if you look earlier in the document it does say std::size, so I changed this to be consistent with the earlier mention. Which version should we keep? std::size, std::ssize, both, something else?
As additional context, what the doc say is "std::size-aware" really means satisfying this concept:
https://github.com/hsutter/cppfront/blob/main/include/cpp2util.h#L531-L532
There was a problem hiding this comment.
I've started a review, and updated this in my local version to list both of them. For details, it uses ssize when you use a signed value and size for an unsigned value.
|
@gregmarr feel free to steal all the changes in this PR and let me know so I can close it in favor of yours. |
|
@DyXel probably easier for you to just remove that one. It's going to be a while before I get much further through it. I'm traveling tomorrow. |
|
Thanks! |
jarzec
pushed a commit
to jarzec/cppfront
that referenced
this pull request
Feb 14, 2024
* docs: fix some typos and confusing wording * restore std::ssize
hsutter
added a commit
that referenced
this pull request
Mar 11, 2024
* Initial files to test MkDocs with Material * Update checkout version * Trying checkout with no version * Back to v3 * Try renaming to docs * Test push to renamed docs branch * Try moving mkdocs.yml to root to unblock CI * Further cleanup to get things in the right directories * Finish moving from `/docs/docs` to `/docs` Added local hosting instructions in the YAML file This renders beautifully locally, but for some reason it doesn't render properly on GitHub Pages yet. One possible reason is the `pages-build-deployment` workflow that GitHub Pages created on my initial attempt to use Pages (before trying MkDocs) is still running (and I can't figure out how to get rid of it) and it appears to be interfering with the `docs` workflow I created for MkDocs If someone has ideas on how to debug this, please open an issue or email me - thx! * Add "Cppfront reference," and start writing "Cpp2 reference" * Merged documentation from blog posts, and unary operators `_` wildcard, including in `inspect` and explicit discard Named `break` and `continue` `type` declaration syntax Explicit `this` `operator=` Chained comparisons Metafunctions overview `@enum` and `@flag_enum` `@union` * Integrate links to wiki design notes * Add more sections Type qualifiers Binary operators `is` and update chained comparisons * Add `as` and `inspect` * Document declarations, improve `inspect` discussion * Fix a few typos * Add Hello-world xref * Update mkdocs.yml * Improve mixed files examples and flow * Overview editorial improvements * Minor cleanup * docs: fix some typos and confusing wording (#976) * docs: fix some typos and confusing wording * restore std::ssize * Fix table of content display -> rhs of page * Add section navigation Reorganize sources Fix long code lines to avoid horizontal scroll bars * Organize the welcome info into three pages And try to use extra CSS to tweak the navigation pane * Disable regression tests on this branch * Add more types and `operator=` material And do further cleanup on the docs structure * Add keywords, objects, and heap allocation * Add `main` * Reviewing cppfront docs (#982) * Reviewing cppfront docs * integrations.md * expressions and objects * Fix "lines 8, 9, and 15" wording * Mention UFCS * Function outputs and explicit discard * Add definite initialization section And: - add placeholder for contracts - add some is/as side-by-side examples - add parameter passing styles * Update CTAD description in hello-world.md (#984) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Embiggen text font, add `move` and `out` arguments And code block cleanup: - highlight key lines in all code blocks - remove redundant "Example:" in code block titles - add a chained comparisons example * Fix small typo in common.md (#985) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Changes to expressions.md (#986) * Update expressions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Minor tweak to not lose "dynamic" types --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Another round of docs updates (#983) * types * metafunctions * Taking a pass over the updates, and adding that `that` must be `in` or `move` * Remove TODO comment for now Not sure of its meaning, we can add again later --------- Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Add syntax highlighting for inline code blocks using `#!cpp` shebangs Note: I deliberately did not add shebangs for: - `inline code` that wouldn't benefit from them (e.g., had nothing significant to highlight) so as to keep the Markdown more readable - `inline code` that I didn't want to highlight, mainly Cpp2 code that used Cpp1 reserved keywords in a non-reserved way (mainly metafunctions like @enum and @union) * Move function calls to expressions * Add capture section And add Cpp1 lowering notes for parameter passing * Add Mermaid build diagram * Add TODO for `member = _;` * Add interpolation formatting, and other minor cleanup * Expand comparisons section Also add short anchor names to all subsections that don't already have them And make anchor names all lowercase-like-this * Update declarations.md (#988) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Follow up merge with additional examples, and update highlighted linenos * Update Capture sections in expressions.md (#987) * Update expressions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Update highlighted linenos And a couple of other fixes, including that I meant to write "ish" not "sh" (fixing my own typo!) --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Signed-off-by: Herb Sutter <herb.sutter@gmail.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * More docs reviews (#990) * Add more functions material Return values Branches Loops Template parameters * Changes to functions.md (#998) * Update functions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Tweak comments for divide example --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Fill in some TODO's * Add requires, namespaces, using, and namespace/type/function/object aliases * Update aliases.md (#1005) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Add generality notes: Function defaults, and function <-> block/stmt unification * Merge previous commit * Update functions.md (#1011) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Update declarations.md (#1010) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Complete the metafunctions section * Update metafunctions.md (#1015) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Add contracts documentation * Remove modules documentation stub since that's not supported yet * Fix comment typo --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Signed-off-by: Herb Sutter <herb.sutter@gmail.com> Co-authored-by: Dylam De La Torre <DyXel04@gmail.com> Co-authored-by: gregmarr <gregmarr@users.noreply.github.com> Co-authored-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com>
hsutter
added a commit
that referenced
this pull request
Mar 15, 2024
* Initial files to test MkDocs with Material * Update checkout version * Trying checkout with no version * Back to v3 * Try renaming to docs * Test push to renamed docs branch * Try moving mkdocs.yml to root to unblock CI * Further cleanup to get things in the right directories * Finish moving from `/docs/docs` to `/docs` Added local hosting instructions in the YAML file This renders beautifully locally, but for some reason it doesn't render properly on GitHub Pages yet. One possible reason is the `pages-build-deployment` workflow that GitHub Pages created on my initial attempt to use Pages (before trying MkDocs) is still running (and I can't figure out how to get rid of it) and it appears to be interfering with the `docs` workflow I created for MkDocs If someone has ideas on how to debug this, please open an issue or email me - thx! * Add "Cppfront reference," and start writing "Cpp2 reference" * Merged documentation from blog posts, and unary operators `_` wildcard, including in `inspect` and explicit discard Named `break` and `continue` `type` declaration syntax Explicit `this` `operator=` Chained comparisons Metafunctions overview `@enum` and `@flag_enum` `@union` * Integrate links to wiki design notes * Add more sections Type qualifiers Binary operators `is` and update chained comparisons * Add `as` and `inspect` * Document declarations, improve `inspect` discussion * Fix a few typos * Add Hello-world xref * Update mkdocs.yml * Improve mixed files examples and flow * Overview editorial improvements * Minor cleanup * docs: fix some typos and confusing wording (#976) * docs: fix some typos and confusing wording * restore std::ssize * Fix table of content display -> rhs of page * Add section navigation Reorganize sources Fix long code lines to avoid horizontal scroll bars * Organize the welcome info into three pages And try to use extra CSS to tweak the navigation pane * Disable regression tests on this branch * Add more types and `operator=` material And do further cleanup on the docs structure * Add keywords, objects, and heap allocation * Add `main` * Reviewing cppfront docs (#982) * Reviewing cppfront docs * integrations.md * expressions and objects * Fix "lines 8, 9, and 15" wording * Mention UFCS * Function outputs and explicit discard * Add definite initialization section And: - add placeholder for contracts - add some is/as side-by-side examples - add parameter passing styles * Update CTAD description in hello-world.md (#984) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Embiggen text font, add `move` and `out` arguments And code block cleanup: - highlight key lines in all code blocks - remove redundant "Example:" in code block titles - add a chained comparisons example * Fix small typo in common.md (#985) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Changes to expressions.md (#986) * Update expressions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Minor tweak to not lose "dynamic" types --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Another round of docs updates (#983) * types * metafunctions * Taking a pass over the updates, and adding that `that` must be `in` or `move` * Remove TODO comment for now Not sure of its meaning, we can add again later --------- Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Add syntax highlighting for inline code blocks using `#!cpp` shebangs Note: I deliberately did not add shebangs for: - `inline code` that wouldn't benefit from them (e.g., had nothing significant to highlight) so as to keep the Markdown more readable - `inline code` that I didn't want to highlight, mainly Cpp2 code that used Cpp1 reserved keywords in a non-reserved way (mainly metafunctions like @enum and @union) * Move function calls to expressions * Add capture section And add Cpp1 lowering notes for parameter passing * Add Mermaid build diagram * Add TODO for `member = _;` * Add interpolation formatting, and other minor cleanup * Expand comparisons section Also add short anchor names to all subsections that don't already have them And make anchor names all lowercase-like-this * Update declarations.md (#988) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Follow up merge with additional examples, and update highlighted linenos * Update Capture sections in expressions.md (#987) * Update expressions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Update highlighted linenos And a couple of other fixes, including that I meant to write "ish" not "sh" (fixing my own typo!) --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Signed-off-by: Herb Sutter <herb.sutter@gmail.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * More docs reviews (#990) * Add more functions material Return values Branches Loops Template parameters * Changes to functions.md (#998) * Update functions.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Tweak comments for divide example --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> * Fill in some TODO's * Add requires, namespaces, using, and namespace/type/function/object aliases * Update aliases.md (#1005) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Add generality notes: Function defaults, and function <-> block/stmt unification * Merge previous commit * Update functions.md (#1011) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Update declarations.md (#1010) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Complete the metafunctions section * Update metafunctions.md (#1015) Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> * Add contracts documentation * Remove modules documentation stub since that's not supported yet * Fix comment typo * Update contracts.md Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> --------- Signed-off-by: Neil Henderson <2060747+bluetarpmedia@users.noreply.github.com> Signed-off-by: Herb Sutter <herb.sutter@gmail.com> Co-authored-by: Herb Sutter <herb.sutter@gmail.com> Co-authored-by: Dylam De La Torre <DyXel04@gmail.com> Co-authored-by: gregmarr <gregmarr@users.noreply.github.com>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This is what I caught on my first reading. Looks good so far!