API comment

[Mike Hearn]

Hi,

Lately I've been working on a project that uses DBUS, and one thing that
confused me was the memory allocation policy for message iterators. I
assumed that it was iterating over the internal contents of the
demarshalled message and therefore strings returned by
dbus_message_iter_get_string should be treated as read-only, non-freeable
memory. 

Apparently this isn't the case, and you have to free the memory returned.
This isn't documented in the API docs as far as I can see. Even more
confusing it seems DBUS uses its own malloc on top of the systems malloc
so you have to use dbus_free and not regular free on these strings.

I was going to submit a patch to the docs for this, but I'm not sure where
best to put this information. Duplicating it in each iter API description
seems overkill, but it has to be somewhere people will see it. Maybe just
a "free the result with dbus_free." in each iter get method which returns
alloced memory would be best?

thanks -mike