Reviewing GVariant

[Matthias Clasen <matthias clasen gmail com>]

So, today I've built the gsettings branch and set out to review
GVariant to make sure it is ready to be merged. I started by reading
the docs,  and I can't help myself, but I still don't like this
GVariantType thing very much. After toiling on this for months, it is
probably as obvious to Ryan as GType is to Tim, but for the rest of
us, not so much.

Just to run down the concepts you meet while reading this chapter,
mostly without introduction or explanation:
- type classes
- basic types, maybe types, container types
- 'any' types
- generic types
- variant types and type strings
- element types
- generic tuple type
- wildcard types and concrete types
- type 'matching'

I'd really like to call for some reduced excess and some clarity of exposition.

- This whole thing would be a lot more digestible if you added a long
introduction that explains the type system and introduced the
terminology.

- If you can't explain clearly in the docs why type classes are a
useful thing to have, do away with them.

- Get your terminology straight. Do types 'match' other types or do
they match values ? Are generic types the same as any types ? And
maybe the same as wildcard types as well ?

- Unexplained obscurities: Whats this business with defining tuple
types via callbacks ?



On to the GVariant docs.

The terminological uncertainty continues. Does a GVariant _have_ a
value, or _is_ it a value ? The introduction says it has a value,
whereas the rest of the docs seem to be written assuming that a
variant is a value.

"'r' means exactly the same as 'r'" ?!

"Nested '@' characters may not appear." - this is unclear. Do you mean
"Consecutive '@' characters may not appear." ?

g_variant_print() should xref g_variant_markup_print().

GVariantIter docs seem to confuse next() and next_value(). E.g. they
talk about next() returning NULL when in reality it returns FALSE.

The concepts of flattening and serialization could be explained in the
introduction.


(I've not stopped to point out the numerous instances of parameter
name confusion).


So much for today, I'll look at the code tomorrow.


Matthias