-/* Return a string based on TEXT which must be encoded using FROM.
- The returned string will be encoded in TO.
- If length is not -1, then it must be the number of bytes in TEXT.
- The returned string must be freed when no longer required.
+/*
+Converts the string TEXT, which should be encoded in FROM-encoding, to a
+dynamically allocated string in TO-encoding. Any characters which cannot
+be converted will be represented by '?'.
+
+LENGTH should be the length of the string or -1, if null terminated.
+
+The returned string will be allocated on POOL.
+
+This function's behaviour differs from that of g_convert_with_fallback provided
+by GLib. The GLib function will fail (returns NULL) if any part of the input
+string is not valid in the declared input encoding. This function however perseveres
+even in the presence of badly encoded input.