From ea592296b8d56c10c16c2b410584a0a42f5eae2d Mon Sep 17 00:00:00 2001 From: Wouter van Oortmerssen Date: Fri, 24 Oct 2014 11:15:37 -0700 Subject: [PATCH] Various documentation improvements. Change-Id: Iacea45ae0f602f49e46de472286a7a77ee20c301 --- docs/html/md__go_usage.html | 5 +++-- docs/html/md__java_usage.html | 2 +- docs/html/md__schemas.html | 5 +++-- docs/source/GoUsage.md | 14 ++++++++++++-- docs/source/JavaUsage.md | 3 ++- docs/source/Schemas.md | 10 +++++++--- 6 files changed, 28 insertions(+), 11 deletions(-) diff --git a/docs/html/md__go_usage.html b/docs/html/md__go_usage.html index f9c29c892..3ebc8b6a2 100644 --- a/docs/html/md__go_usage.html +++ b/docs/html/md__go_usage.html @@ -87,15 +87,16 @@ $(document).ready(function(){initNavTree('md__go_usage.html','');});
example.MonsterAddTest(builder, mon2)
example.MonsterAddTest4(builder, test4s)
mon := example.MonsterEnd(builder)
-

Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the Vec3 is an inline component of Monster, it has to be created right where it is added, whereas the name and the inventory are not inline). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field a and a nested struct field b (which has fields c and d), then the arguments will be a, c and d.

+

Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the Vec3 is an inline component of Monster, it has to be created right where it is added, whereas the name and the inventory are not inline, and must be created outside of the table creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field a and a nested struct field b (which has fields c and d), then the arguments will be a, c and d.

Vectors also use this start/end pattern to allow vectors of both scalar types and structs:

example.MonsterStartInventoryVector(builder, 5)
for i := 4; i >= 0; i-- {
builder.PrependByte(byte(i))
}
inv := builder.EndVector(5)
-

The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front.

+

The generated method 'StartInventoryVector' is provided as a convenience function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer is being constructed back to front. You then pass inv to the corresponding Add call when you construct the table containing it afterwards.

There are Prepend functions for all the scalar types. You use PrependUOffset for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate create function in-line, as shown above in the Monster example.

+

Once you're done constructing a buffer, you call Finish with the root object offset (mon in the example above). Your data now resides in Builder.Bytes. Important to note is that the real data starts at the index indicated by Head(), for Offset() bytes (this is because the buffer is constructed backwards). If you wanted to read the buffer right after creating it (using GetRootAsMonster above), the second argument, instead of 0 would thus also be Head().

Text Parsing

There currently is no support for parsing text (Schema's and JSON) directly from Go, though you could use the C++ parser through cgo. Please see the C++ documentation for more on text parsing.

diff --git a/docs/html/md__java_usage.html b/docs/html/md__java_usage.html index 161d0378a..9e3f2a620 100644 --- a/docs/html/md__java_usage.html +++ b/docs/html/md__java_usage.html @@ -94,7 +94,7 @@ $(document).ready(function(){initNavTree('md__java_usage.html','');});
Monster.startInventoryVector(fbb, 5);
for (byte i = 4; i >=0; i--) fbb.addByte(i);
int inv = fbb.endVector();
-

You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since the buffer is being constructed back to front.

+

You can use the generated method startInventoryVector to conveniently call startVector with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since the buffer is being constructed back to front. You then pass inv to the corresponding Add call when you construct the table containing it afterwards.

There are add functions for all the scalar types. You use addOffset for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate create function in-line, as shown above in the Monster example.

To finish the buffer, call:

Monster.finishMonsterBuffer(fbb, mon);
diff --git a/docs/html/md__schemas.html b/docs/html/md__schemas.html index 28d691081..f8f220beb 100644 --- a/docs/html/md__schemas.html +++ b/docs/html/md__schemas.html @@ -112,7 +112,7 @@ root_type Monster;

Namespaces

These will generate the corresponding namespace in C++ for all helper code, and packages in Java. You can use . to specify nested namespaces / packages.

Includes

-

You can include other schemas files in your current one, e.g.: 

include "mydefinitions.fbs"
+
You can include other schemas files in your current one, e.g.: 
include "mydefinitions.fbs";
 
This makes it easier to refer to types defined elsewhere. include automatically ensures each file is parsed just once, even when referred to more than once.

 
When using the flatc compiler to generate code for schema definitions, only definitions in the current file will be generated, not those from the included files (those you still generate separately).

 
Root type

@@ -128,7 +128,7 @@ root_type Monster;

Comments & documentation

May be written as in most C-based languages. Additionally, a triple comment (///) on a line by itself signals that a comment is documentation for whatever is declared on the line after it (table/struct/field/enum/union/element), and the comment is output in the corresponding C++ code. Multiple such lines per item are allowed.

Attributes

-

Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like deprecated are understood by the compiler, others are simply ignored (like priority), but are available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text).

+

Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like deprecated are understood by the compiler, others are simply ignored (like priority in the example above), but are available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text).

Current understood attributes:

JSON Parsing

The same parser that parses the schema declarations above is also able to parse JSON objects that conform to this schema. So, unlike other JSON parsers, this parser is strongly typed, and parses directly into a FlatBuffer (see the compiler documentation on how to do this from the command line, or the C++ documentation on how to do this at runtime).

diff --git a/docs/source/GoUsage.md b/docs/source/GoUsage.md index d70fc28b5..10dbd5ed2 100644 --- a/docs/source/GoUsage.md +++ b/docs/source/GoUsage.md @@ -75,7 +75,8 @@ Unlike C++, Go does not support table creation functions like 'createMonster()'. This is to create the buffer without using temporary object allocation (since the `Vec3` is an inline component of `Monster`, it has to be created right where it is added, whereas the name and -the inventory are not inline). +the inventory are not inline, and **must** be created outside of the table +creation sequence). Structs do have convenient methods that allow you to construct them in one call. These also have arguments for nested structs, e.g. if a struct has a field `a` and a nested struct field `b` (which has fields `c` and `d`), then the arguments @@ -97,13 +98,22 @@ function which calls 'StartVector' with the correct element size of the vector type which in this case is 'ubyte' or 1 byte per vector element. You pass the number of elements you want to write. You write the elements backwards since the buffer -is being constructed back to front. +is being constructed back to front. You then pass `inv` to the corresponding +`Add` call when you construct the table containing it afterwards. There are `Prepend` functions for all the scalar types. You use `PrependUOffset` for any previously constructed objects (such as other tables, strings, vectors). For structs, you use the appropriate `create` function in-line, as shown above in the `Monster` example. +Once you're done constructing a buffer, you call `Finish` with the root object +offset (`mon` in the example above). Your data now resides in Builder.Bytes. +Important to note is that the real data starts at the index indicated by Head(), +for Offset() bytes (this is because the buffer is constructed backwards). +If you wanted to read the buffer right after creating it (using +`GetRootAsMonster` above), the second argument, instead of `0` would thus +also be `Head()`. + ## Text Parsing There currently is no support for parsing text (Schema's and JSON) directly diff --git a/docs/source/JavaUsage.md b/docs/source/JavaUsage.md index 210cd87cd..e6321b655 100755 --- a/docs/source/JavaUsage.md +++ b/docs/source/JavaUsage.md @@ -125,7 +125,8 @@ does not sit in an array, you can also use the start/end pattern: You can use the generated method `startInventoryVector` to conveniently call `startVector` with the right element size. You pass the number of elements you want to write. Note how you write the elements backwards since -the buffer is being constructed back to front. +the buffer is being constructed back to front. You then pass `inv` to the +corresponding `Add` call when you construct the table containing it afterwards. There are `add` functions for all the scalar types. You use `addOffset` for any previously constructed objects (such as other tables, strings, vectors). diff --git a/docs/source/Schemas.md b/docs/source/Schemas.md index d7b905f8b..650e74db8 100755 --- a/docs/source/Schemas.md +++ b/docs/source/Schemas.md @@ -145,7 +145,7 @@ packages. You can include other schemas files in your current one, e.g.: - include "mydefinitions.fbs" + include "mydefinitions.fbs"; This makes it easier to refer to types defined elsewhere. `include` automatically ensures each file is parsed just once, even when referred to @@ -211,8 +211,8 @@ in the corresponding C++ code. Multiple such lines per item are allowed. Attributes may be attached to a declaration, behind a field, or after the name of a table/struct/enum/union. These may either have a value or not. Some attributes like `deprecated` are understood by the compiler, -others are simply ignored (like `priority`), but are available to query -if you parse the schema at runtime. +others are simply ignored (like `priority` in the example above), but are +available to query if you parse the schema at runtime. This is useful if you write your own code generators/editors etc., and you wish to add additional information specific to your tool (such as a help text). @@ -254,6 +254,10 @@ Current understood attributes: meaning that any value N specified in the schema will end up representing 1<