This bug was submitted to the Debian BTS:

> The documentation for g_get_home_dir specifies:
> 
> | G_CONST_RETURN gchar* g_get_home_dir        (void);
> | 
> | Gets the current user's home directory.
> | 
> | Note that in contrast to traditional Unix tools, this function
> | prefers passwd entries over the HOME environment variable.
> | 	
> | Returns : the current user's home directory.
> 
> Which is obvious self-contradicting, as the home directory is the
> content of the HOME environment variable, and the passwd entry is
> only one possible initial value (if it exists at all).
> 
> As the comment seems to indicate that it does not return the
> home directory, it should rather read something like:
> 
> Gets the current user's possible initial home directory.
>
> Note that the actual home directory for this program can be
> get by reading the HOME environment variable, this is only a
> value which was most likely used by the login program to
> initial set it.
> 
> Returns : the current user's most likely initial home directory.

I think the submitter is right - usual *ix practice is to consider the value of $HOME to be the home directory, so the current documentation is a bit confusing if you're just skimming through the documentation.

TIA,
Marc