[Bug 394687] New: g_get_home_dir documentation confusing

[glib (bugzilla.gnome.org)]

Do not reply to this via email (we are currently unable to handle email
responses and they get discarded).  You can add comments to this bug at
http://bugzilla.gnome.org/show_bug.cgi?id=394687

  glib | docs | Ver: 2.12.x

           Summary: g_get_home_dir documentation confusing
           Product: glib
           Version: 2.12.x
          Platform: Other
        OS/Version: Linux
            Status: UNCONFIRMED
          Severity: minor
          Priority: Normal
         Component: docs
        AssignedTo: gtk-bugs at gtk.org
        ReportedBy: he+bugzilla.g at marcbrockschmidt.de
         QAContact: gtk-bugs at gtk.org
                CC: pkg-gnome-maintainers at lists.alioth.debian.org
     GNOME version: Unspecified
   GNOME milestone: Unspecified


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


-- 
Configure bugmail: http://bugzilla.gnome.org/userprefs.cgi?tab=email