GNOME Bugzilla – Bug 729269
gvariant: Fix confusion between type and format strings in the docs
Last modified: 2014-05-28 10:02:07 UTC
This fixes some confusion between type and format strings in the docs. I’m pretty sure the patch is right.
Created attachment 275493 [details] [review] gvariant: Fix confusion between type and format strings in the docs ‘@’ and ‘&’ are only used in format strings, not type strings.
Created attachment 275495 [details] [review] docs: Remove a duplicated word from the GVariant documentation
Created attachment 275540 [details] [review] docs: Fix some minor typos in the GVariant documentation
Review of attachment 275540 [details] [review]: sure
Thanks for the fast review. Merged to master. Attachment 275493 [details] pushed as fca1b83 - gvariant: Fix confusion between type and format strings in the docs Attachment 275540 [details] pushed as 361a6eb - docs: Fix some minor typos in the GVariant documentation
Created attachment 277212 [details] [review] Revert "gvariant: Fix confusion between type and format strings in the docs" This reverts commit fca1b83be74c9840037cfee84015fd8460cc33f9. The original documentation was correct.
(In reply to comment #6) > The original documentation was correct. How? '@' and '&' are in the GVariant format string documentation section. They are accepted by g_variant_new() and g_variant_get(), whose documentation describes them both as taking GVariant format strings. If I call g_variant_type_new("@as") I get a critical error. What am I missing? :-(
Used as a prefix on a GVariant type string... "as" is the type string. "@" is the prefix. "@as" is the result. This works for any type string. The "(not a format string)" is meant to tell you that you cannot do this with arbitrary format strings. For example, "@^as" is invalid.
Created attachment 277305 [details] [review] I see. The documentation could definitely be improved there, I think. How about this? Although really there should be a formal grammar somewhere instead of this prosaic description. Would you accept a patch for that? gvariant: Clarify type and format strings in the docs '@' and '&' are only used in format strings as prefixes to type strings and not to full format strings.
Review of attachment 277305 [details] [review]: Looks good, but just repeat the text instead of making the user of '&' go hunting for '@'. I don't think that many people would find a formal grammar to be particularly helpful, but I'm sure some would. If you want to take the effort, I'll be happy to look it over and make sure it's correct.
Created attachment 277373 [details] [review] gvariant: Clarify type and format strings in the docs '@' and '&' are only used in format strings as prefixes to type strings and not to full format strings.
Comment on attachment 277373 [details] [review] gvariant: Clarify type and format strings in the docs Sorted. I've added 'GVariant grammar' to my backlog list and will hopefully find time for it in the next few weeks. I will need to do that anyway to validate the conformance of Tartan's GVariant parser, so I might as well produce a formal grammar which can be used to generate test cases and documentation. Attachment 277373 [details] pushed as fd9120d - gvariant: Clarify type and format strings in the docs