[WIP] Revise documentation for Swift 5 stdlib additions #21333
Merged
Conversation
This file contains hidden or 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
natecook1000
changed the title
krilnon
reviewed
Dec 18, 2018
natecook1000
changed the title
It'll render a bit better this way.
- Use the Swift book style for referring to operators by name. - Pick a more standard introducer for referring to a code example.
- Reword some instances of passive voice or unnecessary future tense - Clarify who's doing what when (you, the type, or the compiler?) - Standardize on "you" rather than "client" - Standardize the "for more info, see" blocks - Fix capitalization of headings - Prefer contractions - Remove code voice from a heading - Reword a mixed prose / code voice hyphenation - Fix 'pre-allocate' -> 'preallocate'
In particular, add emphasis to mathematical symbols and equations to match how we document such things elsewhere. I'm using asterisks for single symbols, and underscores for equations because it's easier to read in-source when you don't have to escape multiplication within emphasis.
Tables aren't supported by Swift markup, so this wouldn't render properly in Xcode or on the web. I also reflowed the paragraph below since I added a few words to avoid starting a sentence with code voice.
- Adds a dictionary of spelled out numbers. Only numbers < 10 should be spelled out according to editorial. - Adds abstracts to some of the basic members.
krilnon
reviewed
Jan 3, 2019
This includes parameter descriptions for the xyzw properties and inits, but not for the unlabeled initializers. Combined with the protocol extension method abstracts, this should complete coverage of the concrete types.
Co-Authored-By: natecook1000 <[email protected]>
This makes the description of what a user must implement in a custom string interpolation type to get the behavior they want.
|
These changes are ready for review: @milseman for the Character/UnicodeScalar properties |
|
@swift-ci Please smoke test |
natecook1000
commented
Jan 3, 2019
milseman
approved these changes
Jan 3, 2019
stephentyrone
approved these changes
Jan 3, 2019
|
@swift-ci Please smoke test and merge |
|
@swift-ci Please smoke test |
natecook1000
added a commit
to natecook1000/swift
that referenced
this pull request
Jan 4, 2019
) * Revise the Unicode scalar/Character properties * Minor revisions to `compactMapValues` docs. * Add documentation for AdditiveArithmetic, revise Numeric * Apply minor style updates to count(where:). * Revise string interpolation docs. - Convert table of interpolation examples to a list of examples. Tables aren't supported by Swift markup, so this wouldn't render properly in Xcode or on the web. - Add a description of what a user must implement in a custom string interpolation type to get the behavior they want. * Revise isMultiple(of:) docs. - In particular, add emphasis to mathematical symbols and equations to match how we document such things elsewhere. - I'm using asterisks for single symbols, and underscores for equations because it's easier to read in-source when you don't have to escape multiplication within emphasis. * Add some abstracts to the SIMD vector types. - Adds a dictionary of spelled out numbers. Only numbers < 10 should be spelled out according to editorial. - Adds abstracts to some of the basic members. - Includes parameter descriptions for the xyzw properties and inits, but not for the unlabeled initializers. Combined with the protocol extension method abstracts, this should complete coverage of the concrete types.
natecook1000
added a commit
to natecook1000/swift
that referenced
this pull request
Jan 4, 2019
) Note: This cherry-pick drops the documentation revisions to the Result type, which isn't included on this branch. * Revise the Unicode scalar/Character properties * Minor revisions to `compactMapValues` docs. * Add documentation for AdditiveArithmetic, revise Numeric * Apply minor style updates to count(where:). * Revise string interpolation docs. - Convert table of interpolation examples to a list of examples. Tables aren't supported by Swift markup, so this wouldn't render properly in Xcode or on the web. - Add a description of what a user must implement in a custom string interpolation type to get the behavior they want. * Revise isMultiple(of:) docs. - In particular, add emphasis to mathematical symbols and equations to match how we document such things elsewhere. - I'm using asterisks for single symbols, and underscores for equations because it's easier to read in-source when you don't have to escape multiplication within emphasis. * Add some abstracts to the SIMD vector types. - Adds a dictionary of spelled out numbers. Only numbers < 10 should be spelled out according to editorial. - Adds abstracts to some of the basic members. - Includes parameter descriptions for the xyzw properties and inits, but not for the unlabeled initializers. Combined with the protocol extension method abstracts, this should complete coverage of the concrete types.
shahmishal
added a commit
that referenced
this pull request
Jan 4, 2019
[5.0 12/12] Revise documentation for Swift 5 stdlib additions (#21333)
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 tracking WIP to revise the docs for the additions in SE-0221.