Re: Question about documented functions

[Ergus]

On Sat, Mar 16, 2019 at 02:21:37PM +0200, Eli Zaretskii wrote:
> > Date: Sat, 16 Mar 2019 11:18:47 +0100
> > From: Ergus <address@hidden>
> >
> > Hi. I have a question. The functions/macros to work with lisp variables from C 
> > in lisp.h header file are
> > documented somewhere?
>
> Only in lisp.h itself.  If something there is not clear enough, we
> could improve the commentary.

The problem is that I was trying to figure out the canonical method to
check if a variable was: t from C code (or assign t to a "DEFVAR_LISP"
defined variable). I was looking for something similar to NILP but I
couldn't get it.

For example:

#if DEFINE_KEY_OPS_AS_MACROS
# define XLI(o) lisp_h_XLI (o)
# define XIL(i) lisp_h_XIL (i)
# define XLP(o) lisp_h_XLP (o)
# define XPL(p) lisp_h_XPL (p)
# define CHECK_FIXNUM(x) lisp_h_CHECK_FIXNUM (x)
# define CHECK_SYMBOL(x) lisp_h_CHECK_SYMBOL (x)
# define CHECK_TYPE(ok, predicate, x) lisp_h_CHECK_TYPE (ok, predicate, x)
# define CONSP(x) lisp_h_CONSP (x)
# define EQ(x, y) lisp_h_EQ (x, y)
# define FLOATP(x) lisp_h_FLOATP (x)
# define FIXNUMP(x) lisp_h_FIXNUMP (x)
# define NILP(x) lisp_h_NILP (x)
# define SET_SYMBOL_VAL(sym, v) lisp_h_SET_SYMBOL_VAL (sym, v)
# define SYMBOL_CONSTANT_P(sym) lisp_h_SYMBOL_CONSTANT_P (sym)
# define SYMBOL_TRAPPED_WRITE_P(sym) lisp_h_SYMBOL_TRAPPED_WRITE_P (sym)
# define SYMBOL_VAL(sym) lisp_h_SYMBOL_VAL (sym)
# define SYMBOLP(x) lisp_h_SYMBOLP (x)
# define TAGGEDP(a, tag) lisp_h_TAGGEDP (a, tag)
# define VECTORLIKEP(x) lisp_h_VECTORLIKEP (x)
# define XCAR(c) lisp_h_XCAR (c)
# define XCDR(c) lisp_h_XCDR (c)
# define XCONS(a) lisp_h_XCONS (a)
# define XHASH(a) lisp_h_XHASH (a)
# ifndef GC_CHECK_CONS_LIST
#  define check_cons_list() lisp_h_check_cons_list ()
# endif
# if USE_LSB_TAG
#  define make_fixnum(n) lisp_h_make_fixnum (n)
#  define XFIXNAT(a) lisp_h_XFIXNAT (a)
#  define XFIXNUM(a) lisp_h_XFIXNUM (a)
#  define XSYMBOL(a) lisp_h_XSYMBOL (a)
#  define XTYPE(a) lisp_h_XTYPE (a)
# endif
#endif

It will be helpful for new people (like me), some explanations about
each of them. Expected arguments, and or objectives. And comments like
XFIXNUM can crash so it is needed to protect the code with an if
FIXNUMP. And then what CHECK_FIXNUM is useful for.

I know I need to read more, but it was a bit confusing to figure out the
difference between FIXNUM and FIXNAT.

And functions that are lisp equivalents (CAR CRD) could say that so
newbies can refer to the elisp manual to look for it.