SWIFT-631 Add BSON guide #345
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
mbroadst
suggested changes
Nov 1, 2019
Member
mbroadst
left a comment
mbroadst
left a comment
There was a problem hiding this comment.
Great job on this, I think it's very thorough. I have a few comments, mostly around deeply linking this document to other resources. I imagine a potentially frustrated user going through this will not want to have to open another window and search for some of these things we can link them to immediately. Make sure to use permalinks
kmahar
suggested changes
Nov 1, 2019
Contributor
kmahar
left a comment
kmahar
left a comment
There was a problem hiding this comment.
nice work, just a couple typo fixes and nits
Guides/BSON.md
Outdated
| ``` | ||
| This API provided a number of benefits, the principal one being the seamless integration of standard Swift types (e.g. `Int`) and driver custom ones (e.g `ObjectId`) into `Document`'s methods. It also had a few drawbacks, however. In order for `BSONValue` to be used as an existential type, it could not have `Self` or associated type requirements. This ended being a big restriction as it meant `BSONValue` could not be `Equatable`, `Hashable`, or `Codable`. Instead, all of this functionaltiy was put onto the separate wrapper type `AnyBSONValue`, which was used instead of an existential `BSONValue` in meany places in order to leverage these common protocol conformances. | ||
|
|
||
| Another drawback is that subdocuments lterals could not be inferred and had to be explicitly casted: |
Contributor
There was a problem hiding this comment.
Suggested change
| Another drawback is that subdocuments lterals could not be inferred and had to be explicitly casted: | |
| Another drawback is that subdocument literals could not be inferred and had to be explicitly casted: |
kmahar
approved these changes
Nov 4, 2019
Contributor
kmahar
left a comment
kmahar
left a comment
There was a problem hiding this comment.
two more typos lol, but otherwise LGTM, i don't need to re-review
| @@ -0,0 +1,429 @@ | |||
| # MongoSwift BSON Library | |||
| MongoDB stores and transmits data in the form of [BSON](bsonspec.org) documents, and MongoSwift provides a libary that can be used to work with such documents. The following is an example of some of the functionality provided as part of that: | |||
Contributor
There was a problem hiding this comment.
Suggested change
| MongoDB stores and transmits data in the form of [BSON](bsonspec.org) documents, and MongoSwift provides a libary that can be used to work with such documents. The following is an example of some of the functionality provided as part of that: | |
| MongoDB stores and transmits data in the form of [BSON](bsonspec.org) documents, and MongoSwift provides a library that can be used to work with such documents. The following is an example of some of the functionality provided as part of that: |
oops, missed this one before
Guides/BSON.md
Outdated
| ``` | ||
| This API provided a number of benefits, the principal one being the seamless integration of standard Swift types (e.g. `Int`) and driver custom ones (e.g `ObjectId`) into `Document`'s methods. It also had a few drawbacks, however. In order for `BSONValue` to be used as an existential type, it could not have `Self` or associated type requirements. This ended being a big restriction as it meant `BSONValue` could not be `Equatable`, `Hashable`, or `Codable`. Instead, all of this functionaltiy was put onto the separate wrapper type `AnyBSONValue`, which was used instead of an existential `BSONValue` in many places in order to leverage these common protocol conformances. | ||
|
|
||
| Another drawback is that subdocument lterals could not be inferred and had to be explicitly casted: |
Contributor
There was a problem hiding this comment.
Suggested change
| Another drawback is that subdocument lterals could not be inferred and had to be explicitly casted: | |
| Another drawback is that subdocument literals could not be inferred and had to be explicitly casted: |
mbroadst
approved these changes
Nov 4, 2019
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 PR adds a guide overviewing basic usage of the BSON library as well as a path for migration from the old one. Because we have examples and documentation already, I decided to keep it really basic. Let me know if you think it should have more meat to it or real examples.
Also, I included the migration guide here, but we could consider just putting it at the bottom of the release notes, seeing as we'll have to remove it at some point in the near future if we don't.