Skip to content

docs: Improve API documentation #253

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Oct 7, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,14 +1,20 @@
# Parse-Swift Changelog

### main
[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/1.10.3...main)
[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/1.10.4...main)
* _Contributing to this repo? Add info about your change here to be included in the next release_

### 1.10.4
[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/1.10.3...1.10.4)

__Improvements__
- Improve documentation for ParseObject ([#253](https://github.com/parse-community/Parse-Swift/pull/253)), thanks to [Corey Baker](https://github.com/cbaker6).

### 1.10.3
[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/1.10.2...1.10.3)

__Improvements__
- Update documents to show new Swift 5.5 async/await methods ([#251](https://github.com/parse-community/Parse-Swift/pull/251)), thanks to [Corey Baker](https://github.com/cbaker6).
- Update documents to show new Swift 5.5 async/await methods ([#252](https://github.com/parse-community/Parse-Swift/pull/252)), thanks to [Corey Baker](https://github.com/cbaker6).

### 1.10.2
[Full Changelog](https://github.com/parse-community/Parse-Swift/compare/1.10.1...1.10.2)
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,8 @@ struct GameScore: ParseObject {
/*:
It's recommended the developer adds the emptyObject computed property or similar.
Gets an empty version of the respective object. This can be used when you only need to update a
a subset of the fields of an object as oppose to updating every field of an object.
- note: Using an empty object and updating a subset of the fields reduces the amount of data sent between
a subset of the fields of an object as oppose to updating every field of an object. Using an
empty object and updating a subset of the fields reduces the amount of data sent between
client and server when using `save` and `saveAll` to update objects.
*/
var emptyObject: Self {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -34,8 +34,8 @@ struct GameScore: ParseObject {
/*:
It's recommended the developer adds the emptyObject computed property or similar.
Gets an empty version of the respective object. This can be used when you only need to update a
a subset of the fields of an object as oppose to updating every field of an object.
- note: Using an empty object and updating a subset of the fields reduces the amount of data sent between
a subset of the fields of an object as oppose to updating every field of an object. Using an
empty object and updating a subset of the fields reduces the amount of data sent between
client and server when using `save` and `saveAll` to update objects.
*/
var emptyObject: Self {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -36,8 +36,8 @@ struct User: ParseUser {
/*:
It's recommended the developer adds the emptyObject computed property or similar.
Gets an empty version of the respective object. This can be used when you only need to update a
a subset of the fields of an object as oppose to updating every field of an object.
- note: Using an empty object and updating a subset of the fields reduces the amount of data sent between
a subset of the fields of an object as oppose to updating every field of an object. Using an
empty object and updating a subset of the fields reduces the amount of data sent between
client and server when using `save` and `saveAll` to update objects.
*/
var emptyObject: Self {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -39,8 +39,8 @@ struct Installation: ParseInstallation {
/*:
It's recommended the developer adds the emptyObject computed property or similar.
Gets an empty version of the respective object. This can be used when you only need to update a
a subset of the fields of an object as oppose to updating every field of an object.
- note: Using an empty object and updating a subset of the fields reduces the amount of data sent between
a subset of the fields of an object as oppose to updating every field of an object. Using an
empty object and updating a subset of the fields reduces the amount of data sent between
client and server when using `save` and `saveAll` to update objects.
*/
var emptyObject: Self {
Expand Down
5 changes: 2 additions & 3 deletions Scripts/jazzy.sh
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,8 @@ bundle exec jazzy \
--github_url https://github.com/parse-community/Parse-Swift \
--root-url http://parseplatform.org/Parse-Swift/api/ \
--module-version ${BUILD_VERSION} \
--theme apple \
--theme fullwidth \
--skip-undocumented \
--output ./docs/api \
--build-tool-arguments -scheme,'ParseSwift (iOS)',-destination,'name=iPhone 12 Pro Max' \
--module ParseSwift \
--swift-build-tool spm \
--build-tool-arguments -Xswiftc,-swift-version,-Xswiftc,5
54 changes: 49 additions & 5 deletions Sources/ParseSwift/Objects/ParseObject.swift
Original file line number Diff line number Diff line change
Expand Up @@ -12,19 +12,63 @@ import Foundation
Objects that conform to the `ParseObject` protocol have a local representation of data persisted to the Parse cloud.
This is the main protocol that is used to interact with objects in your app.

If you plan to use custom encoding/decoding, be sure to add `objectId`, `createdAt`, `updatedAt`, and
`ACL` to your `ParseObject` `CodingKeys`.
The Swift SDK is designed for your `ParseObject`s to be "value types" (structs).
If you are using value types the the compiler will assist you with conforming to `ParseObject` protocol. If you
are thinking of using reference types, see the warning.

It's recommended the developer adds the emptyObject computed property or similar.
Gets an empty version of the respective object. This can be used when you only need to update a
a subset of the fields of an object as oppose to updating every field of an object. Using an empty object and updating
a subset of the fields reduces the amount of data sent between client and server when using `save` and `saveAll`
to update objects. You should add the following properties in your `ParseObject`'s:

var emptyObject: Self {
var object = Self()
object.objectId = objectId
object.createdAt = createdAt
return object
}

When designing applications for SwiftUI, it is recommended to make all `ParseObject`'s conform to
`Identifiable`. This can be accomplised by doing the following:

- note: It is recommended to make your`ParseObject`s "value types" (structs).
If you are using value types there isn't much else you need to do but to conform to ParseObject. If you are thinking of
using reference types, see the warning.
struct GameScore: ParseObject, Identifiable {

// Add this computed property to conform to `Identifiable` for iOS13+
var id: String {
guard let objectId = self.objectId else {
return UUID().uuidString
}
return objectId
}

// These are required for any Object.
var objectId: String?
var createdAt: Date?
var updatedAt: Date?
var ACL: ParseACL?

// Your own properties.
var score: Int = 0
var location: ParseGeoPoint?
var name: String?
var myFiles: [ParseFile]?
}

- important: It is recommended that all added properties be optional properties so they can eventually be used as
Parse `Pointer`'s. If a developer really wants to have a required key, they should require it on the server-side or
create methods to check the respective properties on the client-side before saving objects. See
[here](https://github.com/parse-community/Parse-Swift/issues/157#issuecomment-858671025)
for more information.
- warning: If you plan to use "reference types" (classes), you are using at your risk as this SDK is not designed
for reference types and may have unexpected behavior when it comes to threading. You will also need to implement
your own `==` method to conform to `Equatable` along with with the `hash` method to conform to `Hashable`.
It is important to note that for unsaved `ParseObject`'s, you won't be able to rely on `objectId` for
`Equatable` and `Hashable` as your unsaved objects won't have this value yet and is nil. A possible way to
address this is by creating a `UUID` for your objects locally and relying on that for `Equatable` and `Hashable`,
otherwise it's possible you will get "circular dependency errors" depending on your implementation.
- note: If you plan to use custom encoding/decoding, be sure to add `objectId`, `createdAt`, `updatedAt`, and
`ACL` to your `ParseObject` `CodingKeys`.
*/
public protocol ParseObject: Objectable,
Fetchable,
Expand Down
2 changes: 1 addition & 1 deletion Sources/ParseSwift/ParseConstants.swift
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,7 @@ import Foundation

enum ParseConstants {
static let sdk = "swift"
static let version = "1.10.3"
static let version = "1.10.4"
static let fileManagementDirectory = "parse/"
static let fileManagementPrivateDocumentsDirectory = "Private Documents/"
static let fileManagementLibraryDirectory = "Library/"
Expand Down