Should supply a more clear API doc

[navigator117]

Should supply a more clear API doc

[mikkelfj]

could be better, but it is not a priority - if someone wants to contribute I'd be happe to set something up with http://www.mkdocs.org or similar. At the very least you need to specify which parts of the API you are concerend with. The untyped builder API in flatcc.h is documented only in the header file, and I believe this is an adequate level.

For the generated code, there is room for improvement with lots of examples etc. but it is also a signficant amount of work. The primary monster_test.c file is intended to provide working examples.

[navigator117]

As it's too many macros in flatbuffer_common_builder.h and flatbuffer_common_reader.h, It's hard know which function I can use for what type defined in schema file. doc/builder.md can help but not more.

[mikkelfj]

Yes, it can be a bit confusing. How do you propose to improve on this?

[navigator117]

How about use gcc -E -P like feature to expand the macro, or, add comments to functions in generated builder.h/reader.h files, and propose the best practice functions set in these comments?

[mikkelfj]

gcc macro expansion would expose a huge number of internal macros that would not be helpful.

builder.md does document some or most generated macros, such as flatbuffer_string_vec_len but does not explicitly name them all. There are many very similar methods. builder.md also does not discuss reader only macros but they are hinted at in the README. This could be more consistent.

Also note that it isn't really macros. The macros are used to generate type safe inline functions similar to how C++ templates work.

I think the solution is the make README smaller and have documention like builder.md cover both read and write, and add more examples and list more supported functions as a reference section. But again, this is a fair amount of work.

If you, or someone else, is willing to compile a reference.md file of functions, I'd be happy to fill in the gaps and advice on how to extract information.

[mikkelfj]

Apart from offloading work, it would be good if someone else wrote some documentation because things that are clear to me may not be clear to others.

[mikkelfj]

At least there is now a table of contents in the README and in doc/builder.md and benchmarks have been moved to a separate file.

[mikkelfj]

See #88 and https://github.com/dvidelabs/flatcc#use-of-macros-in-generated-code, https://github.com/dvidelabs/flatcc#extracting-documentation
for a partial solution to this problem

[mikkelfj]

Closing this as the provided script works pretty well, although not perfect.

Note that string operations like flatbuffers_string_ can also be extracted with the tool.

You still have to manually specify what you need documentation on, but it also allows you to drill down to very specific operations like vector push etc.