[Emacs-diffs] emacs-26 8ac621b: Document DEFUN attributes

[Eli Zaretskii]

branch: emacs-26
commit 8ac621bb5594786c66cc724864e6037c8c650774
Author: Eli Zaretskii <address@hidden>
Commit: Eli Zaretskii <address@hidden>

    Document DEFUN attributes
    
    * doc/lispref/internals.texi (Writing Emacs Primitives): Document
    specification of function attributes in DEFUN.
---
 doc/lispref/internals.texi | 39 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/doc/lispref/internals.texi b/doc/lispref/internals.texi
index 6d25eb1..398ea8d 100644
--- a/doc/lispref/internals.texi
+++ b/doc/lispref/internals.texi
@@ -735,7 +735,7 @@ Lisp form.  For example:
 
 @example
 @group
-DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED,
+DEFUN ("foo", Ffoo, Sfoo, 0, UNEVALLED, 0
        "(list (read-char-by-name \"Insert character: \")\
               (prefix-numeric-value current-prefix-arg)\
               t))",
@@ -761,6 +761,43 @@ arguments.
 All the usual rules for documentation strings in Lisp code
 (@pxref{Documentation Tips}) apply to C code documentation strings
 too.
+
+The documentation string can be followed by a list of C function
+attributes for the C function that implements the primitive, like
+this:
+
address@hidden
address@hidden
+DEFUN ("bar", Fbar, Sbar, 0, UNEVALLED, 0
+  doc: /* @dots{} /*
+  attributes: @var{attr1} @var{attr2} @dots{})
address@hidden group
address@hidden example
+
address@hidden
+You can specify more than a single attribute, one after the other.
+Currently, only the following attributes are recognized:
+
address@hidden @code
address@hidden noreturn
+Declares the C function as one that never returns.  This corresponds
+to the C11 keyword @code{_Noreturn} and to @address@hidden
+((__noreturn__))}} attribute of GCC (@pxref{Function Attributes,,,
+gcc, Using the GNU Compiler Collection}).
+
address@hidden const
+Declares that the function does not examine any values except its
+arguments, and has no effects except the return value.  This
+corresponds to @address@hidden ((__const__))}} attribute of
+GCC.
+
address@hidden noinline
+This corresponds to @address@hidden ((__noinline__))}}
+attribute of GCC, which prevents the function from being considered
+for inlining.  This might be needed, e.g., to countermand effects of
+link-time optimizations on stack-based variables.
address@hidden table
+
 @end table
 
   After the call to the @code{DEFUN} macro, you must write the