BigfootDev/flatbuffers
1
0
Fork 1
mirror of https://github.com/google/flatbuffers.git synced 2026-06-30 05:10:02 +00:00
Code Issues Packages Projects Releases Wiki Activity

Improves documentation, and adding DocC (#6784)

Browse Source 
Finished documenting flatbuffersbuilder

Replaces swift 5.5 with 5.2 packages

Starts building the tutorial for xcode 13

Finishes building the tutorial for xcode 13

Removes docc files from old swift versions

Updates swift style guide
This commit is contained in:
mustiikhalil
2021-09-27 20:59:19 +02:00
committed by GitHub
parent e2b26ee19b
commit f63c130c28
56 changed files with 1214 additions and 163 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
swift/Sources/FlatBuffers/Documentation.docc/Tutorials/Tutorial_Table_of_Contents.tutorial Normal file
View File

@@ -0,0 +1,14 @@
@Tutorials(name: "Starting with FlatBuffers") {
@Intro(title: "Starting with FlatBuffers") {
FlatBuffers is an efficient cross platform serialization library for C++,
C#, C, Go, Java, Kotlin, JavaScript, Lobster, Lua, TypeScript, PHP, Python, Rust and Swift.
It was originally created at Google for game development and other performance-critical applications.
}
@Chapter(name: "Generating your code") {
Start by generating your first FlatBuffers objects.
@Image(source: tutorial_cover_image_1.png, alt: "A code structure for a base struct in flatbuffers")
@TutorialReference(tutorial: "doc:creating_flatbuffer_schema")
@TutorialReference(tutorial: "doc:create_your_first_buffer")
@TutorialReference(tutorial: "doc:reading_bytebuffer")
}
}

72
swift/Sources/FlatBuffers/Documentation.docc/Tutorials/create_your_first_buffer.tutorial Normal file
View File

@@ -0,0 +1,72 @@
@Tutorial(time: 5) {
@Intro(title: "After having our code generated") {
After generating the code from the previous section, we will know start creating our monster object.
We will create a monster object called orc.
}
@Section(title: "Building your first buffer") {
@ContentAndMedia {}
@Steps {
@Step {
Starting with a new file, we will create our very first Flatbuffer.
@Code(name: "ViewController.swift", file: "swift_code_1.swift")
}
@Step {
First, we need to import ``FlatBuffers``
@Code(name: "ViewController.swift", file: "swift_code_2.swift")
}
@Step {
We need to create an instance of the `FlatBufferBuilder`, which will contain the buffer as it grows.
You can pass an initial size of the buffer (here 1024 bytes), which will grow automatically if needed.
@Code(name: "ViewController.swift", file: "swift_code_3.swift")
}
@Step {
After creating the builder, we can start serializing our data. Before we make our orc Monster,
let's create some Weapons: a Sword and an Axe. However we will start by naming our weapons as `Sword` and `Axe`
@Code(name: "ViewController.swift", file: "swift_code_4.swift")
}
@Step {
After naming the weapons, we will create two weapon objects with the damage that the weapon is going to deal.
That's done by calling the `start` Method on each table you will be creating, in this case its called `startWeapon`
and finished by calling `end`.
@Code(name: "ViewController.swift", file: "swift_code_5.swift")
}
@Step {
We will take our (Sword and Axe) serialized data and serialize their offsets as a vector of tables into our `ByteBuffer`.
So we can reference them later on from our Monster Object
@Code(name: "ViewController.swift", file: "swift_code_6.swift")
}
@Step {
We will add our Monster name as a string value just like we did with the weapons.
@Code(name: "ViewController.swift", file: "swift_code_7.swift")
}
@Step {
We will create a path that our monster should be using while roaming in its den. To create a vector of paths we would us
`createVector(ofStructs: [])` which will take a Native `Swift` struct that has been padded to fit the `FlatBuffers` standards.
There are usually two ways of creating vectors in `FlatBuffers` which you can see in commented out code.
And thus there are multiple convenience methods that will cover all the bases
when trying to create a vector so that you dont have to create it with `start` and `end`
@Code(name: "ViewController.swift", file: "swift_code_8.swift")
}
@Step {
Now to serialize our data into our `Monster` object. Which again there are two ways of doing, by calling the `create` method or
by serializing the objects yourself. What we added to our Monster were the `Equipped Type` and the `Equipped` union itself, which
allows the Monster to have the `Axe` as his equipped weapon.
Important: Unlike structs, you should not nest tables or other objects,
which is why we created all the `strings/vectors/tables` that this monster refers to before start.
If you try to create any of them between start and end, you will get an `assert`.
@Code(name: "ViewController.swift", file: "swift_code_9.swift")
}
@Step {
Finally you can just finalize the buffer by calling `builder.finish` and get the Byte array from the buffer.
@Code(name: "ViewController.swift", file: "swift_code_10.swift")
}
}
}
}

47
swift/Sources/FlatBuffers/Documentation.docc/Tutorials/creating_flatbuffer_schema.tutorial Normal file
View File

@@ -0,0 +1,47 @@
@Tutorial(time: 2) {
@Intro(title: "Creating a schema") {
You will need to have the FlatBuffer compiler to be installed on your device
}
@Section(title: "Creating a schema") {
@ContentAndMedia {}
@Steps {
@Step {
Start by creating a new empty folder called `monster.fbs`. We want to create a Monster table, that contains
position, color, and basic information about the monster.
@Code(name: "monster.fbs", file: "monster_step_1.fbs")
}
@Step {
We will start by adding our Color object. We will be using an enumerate, to represent this object
@Code(name: "monster.fbs", file: "monster_step_2.fbs")
}
@Step {
We will add a position object and will use a struct to represent that type of data. Where we will need the monsters
x and y positions.
@Code(name: "monster.fbs", file: "monster_step_3.fbs")
}
@Step {
Then we will be creating our Monster object of type table. This will contain the current position of our
monster and its color
@Code(name: "monster.fbs", file: "monster_step_4.fbs")
}
@Step {
Our Monster is missing a name, mana, hp, name, equipped Weapon, weapons, and path. We will be adding these
fields to our table with a proper data type for each. Example; weapons, and path would be a vector of data.
@Code(name: "monster.fbs", file: "monster_step_5.fbs")
}
@Step {
Now we are missing two data types here, `Weapon` and `Equipment`. And since Equipment can be a weapon, we will be using
a `Union` enumerate that can contain all the equipment that you would want your monster to have. And the weapon can simply
have a name and amount of damage
@Code(name: "monster.fbs", file: "monster_step_6.fbs")
}
@Step {
And to finalize our monster table, we can add a root type of type Monster.
Then run the command `flatc --swift monster.fbs`
Note: Make sure to import the file to your xcode project.
@Code(name: "monster.fbs", file: "monster_step_7.fbs")
}
}
}
}

27
swift/Sources/FlatBuffers/Documentation.docc/Tutorials/reading_bytebuffer.tutorial Normal file
View File

@@ -0,0 +1,27 @@
@Tutorial(time: 2) {
@Intro(title: "Reading ByteBuffers") {
After getting our ByteBuffer created, we can now read it.
}
@Section(title: "Reading your first buffer") {
@ContentAndMedia {}
@Steps {
@Step {
After fetching the data from disk or network you need to access that data, and that can be done.
By simply calling `getCheckedRoot`, which checks if the data is valid before enabling you to read from a corrupt buffer.
however, if you are sure that the data is 100% correct you can simply call `getRoot`
@Code(name: "ViewController.swift", file: "swift_code_11.swift")
}
@Step {
Now since we have a Monster object, all the fields can be accessed by simply fetching the data. Note, Deprecated fields will not
show up
@Code(name: "ViewController.swift", file: "swift_code_12.swift")
}
@Step {
And you can access union types as easy as this
@Code(name: "ViewController.swift", file: "swift_code_13.swift")
}
}
}
}