[Guile-commits] 01/01: Improve the documentation for 'nil?'.

[Mark H. Weaver]

mhw pushed a commit to branch stable-2.2
in repository guile.

commit b44f505f1571fc9c42e58982f161a9cfc81fb7f4
Author: Mark H Weaver <address@hidden>
Date:   Sun Oct 14 01:32:58 2018 -0400

    Improve the documentation for 'nil?'.
    
    * libguile/boolean.c (scm_nil_p): Improve docstring.
    * doc/ref/api-languages.texi (Nil): Add documentation for 'nil?', along
    with a description of how Elisp interprets Scheme booleans and
    end-of-list.
---
 doc/ref/api-languages.texi | 22 ++++++++++++++++++++--
 libguile/boolean.c         | 13 +++++++++++--
 2 files changed, 31 insertions(+), 4 deletions(-)

diff --git a/doc/ref/api-languages.texi b/doc/ref/api-languages.texi
index 839e6ea..763e798 100644
--- a/doc/ref/api-languages.texi
+++ b/doc/ref/api-languages.texi
@@ -1,7 +1,7 @@
 @c -*-texinfo-*-
 @c This is part of the GNU Guile Reference Manual.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010
address@hidden   Free Software Foundation, Inc.
address@hidden Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 
2016,
address@hidden   2017, 2018 Free Software Foundation, Inc.
 @c See the file guile.texi for copying conditions.
 
 @node Other Languages
@@ -108,6 +108,24 @@ code to maintain their current semantics. @code{nil}, 
which in Elisp
 would just be written and read as @code{nil}, in Scheme has the external
 representation @code{#nil}.
 
+In Elisp code, @code{#nil}, @code{#f}, and @code{'()} behave like
address@hidden, in the sense that they are all interpreted as @code{nil} by
+Elisp @code{if}, @code{cond}, @code{when}, @code{not}, @code{null}, etc.
+To test whether Elisp would interpret an object as @code{nil} from
+within Scheme code, use @code{nil?}:
+
address@hidden {Scheme Procedure} nil? obj
+Return @code{#t} if @var{obj} would be interpreted as @code{nil} by
+Emacs Lisp code, else return @code{#f}.
+
address@hidden
+(nil? #nil) @result{} #t
+(nil? #f)   @result{} #t
+(nil? '())  @result{} #t
+(nil? 3)    @result{} #f
address@hidden lisp
address@hidden deffn
+
 This decision to have @code{nil} as a low-level distinct value
 facilitates interoperability between the two languages. Guile has chosen
 to have Scheme deal with @code{nil} as follows:
diff --git a/libguile/boolean.c b/libguile/boolean.c
index f8c7738..635c149 100644
--- a/libguile/boolean.c
+++ b/libguile/boolean.c
@@ -1,4 +1,5 @@
-/*     Copyright (C) 1995, 1996, 2000, 2001, 2006, 2008, 2009, 2010, 2011 Free 
Software Foundation, Inc.
+/* Copyright (C) 1995, 1996, 2000, 2001, 2006, 2008-2011, 2018
+ *   Free Software Foundation, Inc.
  * 
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public License
@@ -64,7 +65,15 @@ SCM_DEFINE (scm_not, "not", 1, 0, 0,
 
 SCM_DEFINE (scm_nil_p, "nil?", 1, 0, 0,
             (SCM x),
-            "Return @code{#t} iff @var{x} is nil, else return @code{#f}.")
+            "Return @code{#t} if @var{x} would be interpreted as @code{nil}\n"
+            "by Emacs Lisp code, else return @code{#f}.\n"
+            "\n"
+            "@example\n"
+            "(nil? #nil) @result{} #t\n"
+            "(nil? #f)   @result{} #t\n"
+            "(nil? '())  @result{} #t\n"
+            "(nil? 3)    @result{} #f\n"
+            "@end example")
 #define FUNC_NAME s_scm_nil_p
 {
   return scm_from_bool (scm_is_lisp_false (x));