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.

1 files changed, 20 insertions, 2 deletions

diff --git a/doc/ref/api-languages.texi b/doc/ref/api-languages.texi
index 839e6eae2..763e79859 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.
-@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010
-@c   Free Software Foundation, Inc.
+@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2010, 2016,
+@c   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
+@code{nil}, 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?}:
+
+@deffn {Scheme Procedure} nil? obj
+Return @code{#t} if @var{obj} would be interpreted as @code{nil} by
+Emacs Lisp code, else return @code{#f}.
+
+@lisp
+(nil? #nil) @result{} #t
+(nil? #f)   @result{} #t
+(nil? '())  @result{} #t
+(nil? 3)    @result{} #f
+@end lisp
+@end 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: