From 4b27c92910ebe57c1d21932df2a85c142516c7b4 Mon Sep 17 00:00:00 2001 From: Wouter van Oortmerssen Date: Thu, 10 Aug 2017 11:25:13 -0700 Subject: [PATCH] Misc documentation fixes. Change-Id: Id7be5baba7d8a11ca050e8d94d95857406690378 --- docs/source/Schemas.md | 10 ++++++++-- docs/source/Tutorial.md | 4 ++++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index 1a3228078..db51ff957 100755 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -278,7 +278,10 @@ Current understood attributes: IDs allow the fields to be placed in any order in the schema. When a new field is added to the schema it must use the next available ID. - `deprecated` (on a field): do not generate accessors for this field - anymore, code should stop using this data. + anymore, code should stop using this data. Old data may still contain this + field, but it won't be accessible anymore by newer code. Note that if you + deprecate a field that was previous required, old code may fail to validate + new data (when using the optional verifier). - `required` (on a non-scalar table field): this field must always be set. By default, all fields are optional, i.e. may be left out. This is desirable, as it helps with forwards/backwards compatibility, and @@ -288,7 +291,10 @@ Current understood attributes: constructs FlatBuffers to ensure this field is initialized, so the reading code may access it directly, without checking for NULL. If the constructing code does not initialize this field, they will get an assert, and also - the verifier will fail on buffers that have missing required fields. + the verifier will fail on buffers that have missing required fields. Note + that if you add this attribute to an existing field, this will only be + valid if existing data always contains this field / existing code always + writes this field. - `force_align: size` (on a struct): force the alignment of this struct to be something higher than what it is naturally aligned to. Causes these structs to be aligned to that amount inside a buffer, IF that diff --git a/docs/source/Tutorial.md b/docs/source/Tutorial.md index 4a4d29661..717d77359 100644 --- a/docs/source/Tutorial.md +++ b/docs/source/Tutorial.md @@ -710,6 +710,10 @@ adding fields to our monster. other `vector`s), collect their offsets into a temporary data structure, and then create an additional `vector` containing their offsets.* +If instead of creating a vector from an existing array you serialize elements +individually one by one, take care to note that this happens in reverse order, +as buffers are built back to front. + For example, take a look at the two `Weapon`s that we created earlier (`Sword` and `Axe`). These are both FlatBuffer `table`s, whose offsets we now store in memory. Therefore we can create a FlatBuffer `vector` to contain these