Update 2023-05-17-enhanced-ergonomics-for-record-types.mdx #689
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
Sure, here's a draft for the documentation change that should make it more clear: --- ### Title: Correction of Record Type Spread Behavior in ReScript v11 Documentation **Change:** Update the section "Record Type Spread" to clarify that fields from different record types cannot share the same name, even if they are of the same type. **Proposed Changes:** Under the section "Record Type Spread", modify the paragraph: "Keeping it as straightforward as possible, type spreads are essentially a 'copy-paste' operation for fields from one or more records to another, inlining the fields from the spread records into the new record. Please note: As for right now it is not possible to override fields in the target record type." To: "Keeping it as straightforward as possible, type spreads are essentially a 'copy-paste' operation for fields from one or more records to another, inlining the fields from the spread records into the new record. Please note: it is not allowed to have fields with the same name in the records being spread, even if they are of the same type. Additionally, it is currently not possible to override fields in the target record type." --- **Reason for the change:** The previous text can lead to confusion, as it could be interpreted that fields with the same name but of the same type can be spread into a new record type. The proposed change provides clarification on this behavior to avoid such misunderstanding. --- You can now create a PR on GitHub using this draft.
ryyppy
approved these changes
May 21, 2023
In this discussion, we sought to clarify the semantics of record type spreading in ReScript v11 as described in the provided documentation. There was a particular focus on the treatment of optional fields when they are spread from one record into another, and how to appropriately phrase this in the documentation.
Key conclusions are:
1. **Record type spread**: The operation is fundamentally a 'copy-paste' mechanism that inlines fields from one or more records into a new record. All properties of the fields (including whether they're optional or mandatory) are preserved in the process.
2. **Unique field names**: Duplicate field names are not allowed across the records being spread, even if the fields share the same type.
3. **Phrasing in the documentation**: In order to reduce confusion and provide clear, concise information, it's recommended to phrase the explanation as follows:
"Record type spreads act as a 'copy-paste' mechanism for fields from one or more records into a new record. This operation inlines the fields from the spread records directly into the new record definition, while preserving their original properties, such as whether they are optional or mandatory. It's important to note that duplicate field names are not allowed across the records being spread, even if the fields share the same type."
These conclusions should aid in improving the clarity and accuracy of the documentation, ensuring it provides an accurate representation of the semantics of record type spreading in ReScript v11.
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.
Sure, here's a draft for the documentation change that should make it more clear:
Title: Correction of Record Type Spread Behavior in ReScript v11 Documentation
Change:
Update the section "Record Type Spread" to clarify that fields from different record types cannot share the same name, even if they are of the same type.
Proposed Changes:
Under the section "Record Type Spread", modify the paragraph:
"Keeping it as straightforward as possible, type spreads are essentially a 'copy-paste' operation for fields from one or more records to another, inlining the fields from the spread records into the new record. Please note: As for right now it is not possible to override fields in the target record type."
To:
"Keeping it as straightforward as possible, type spreads are essentially a 'copy-paste' operation for fields from one or more records to another, inlining the fields from the spread records into the new record. Please note: it is not allowed to have fields with the same name in the records being spread, even if they are of the same type. Additionally, it is currently not possible to override fields in the target record type."
Reason for the change:
The previous text can lead to confusion, as it could be interpreted that fields with the same name but of the same type can be spread into a new record type. The proposed change provides clarification on this behavior to avoid such misunderstanding.
You can now create a PR on GitHub using this draft.