# HG changeset patch
# User Rik <rik@octave.org>
# Date 1428014198 25200
# Node ID cf9b94a89620cefbd2eb55ac242286252b69ef51
# Parent  6babcfbe1a0a3a3f0e12117b45de7a5a5b01aace
Document get_home_directory in Octave manual and NEWS file.

* NEWS: Add get_home_directory to list of new functions.

* system.txi: Add get_home_directory to manual.

* sysdep.cc(Fget_home_directory): Use preferred docstring format of single line
summary sentence followed by second paragragh of explanation.  Add BIST test.

diff -r 6babcfbe1a0a -r cf9b94a89620 NEWS
--- a/NEWS	Thu Apr 02 14:21:43 2015 -0700
+++ b/NEWS	Thu Apr 02 15:36:38 2015 -0700
@@ -204,6 +204,7 @@
       dir_in_loadpath
       flip
       frame2im
+      get_home_directory
       hgload
       hgsave
       ichol
diff -r 6babcfbe1a0a -r cf9b94a89620 doc/interpreter/system.txi
--- a/doc/interpreter/system.txi	Thu Apr 02 14:21:43 2015 -0700
+++ b/doc/interpreter/system.txi	Thu Apr 02 15:36:38 2015 -0700
@@ -406,6 +406,8 @@
 
 @DOCSTRING(unsetenv)
 
+@DOCSTRING(get_home_directory)
+
 @node Current Working Directory
 @section Current Working Directory
 
diff -r 6babcfbe1a0a -r cf9b94a89620 libinterp/corefcn/sysdep.cc
--- a/libinterp/corefcn/sysdep.cc	Thu Apr 02 14:21:43 2015 -0700
+++ b/libinterp/corefcn/sysdep.cc	Thu Apr 02 15:36:38 2015 -0700
@@ -1011,10 +1011,12 @@
 
 DEFUN (get_home_directory, , ,
        "-*- texinfo -*-\n\
-@deftypefn {Built-in Function} {} get_home_directory ()\n\
-Return the current home directory.  On most systems, this is equivalent\n\
-to @code{getenv (\"HOME\")}.  On Windows systems, if @env{HOME} is not\n\
-set in the environment, it is equivalent to\n\
+@deftypefn {Built-in Function} {@var{homedir} =} get_home_directory ()\n\
+Return the current home directory.\n\
+\n\
+On most systems, this is equivalent to @code{getenv (\"HOME\")}.  On Windows\n\
+systems, if the environment variable @env{HOME} is not set then it is\n\
+equivalent to\n\
 @code{fullfile (getenv (\"HOMEDRIVE\"), getenv (\"HOMEPATH\"))}\n\
 @seealso{getenv}\n\
 @end deftypefn")
@@ -1022,6 +1024,13 @@
   return octave_value (octave_env::get_home_directory ());
 }
 
+/*
+%!test
+%! if (! ispc ())
+%!   assert (get_home_directory (), getenv ("HOME")); 
+%! endif
+*/
+
 // This function really belongs in display.cc, but including defun.h in
 // that file results in conflicts with symbols from headers that are
 // needed for X11 and Carbon functions.