From 12ff7ab5e65bda7b890254ff13f0534ddd322f0c Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Sun, 23 Dec 2001 06:38:58 +0000 Subject: Document new doc string format. --- lispref/internals.texi | 26 +++++++++++++++++++------- 1 file changed, 19 insertions(+), 7 deletions(-) (limited to 'lispref/internals.texi') diff --git a/lispref/internals.texi b/lispref/internals.texi index 8e4ee5987d5..13470037586 100644 --- a/lispref/internals.texi +++ b/lispref/internals.texi @@ -444,11 +444,12 @@ appearance.) @smallexample @group DEFUN ("or", For, Sor, 0, UNEVALLED, 0, - "Eval args until one of them yields non-nil; return that value.\n\ -The remaining args are not evalled at all.\n\ + doc: /* Eval args until one of them yields non-nil, then return that value. +The remaining args are not evalled at all. +If all args return nil, return nil. @end group @group -If all args return nil, return nil.") +usage: (or CONDITIONS ...) */) (args) Lisp_Object args; @{ @@ -534,10 +535,21 @@ called interactively. A value of @code{""} indicates a function that should receive no arguments when called interactively. @item doc -This is the documentation string. It is written just like a -documentation string for a function defined in Lisp, except you must -write @samp{\n\} at the end of each line. In particular, the first line -should be a single sentence. +This is the documentation string. It uses C comment syntax rather +than C string syntax because comment syntax requires nothing special +to include multiple lines. The @samp{doc:} identifies the comment +that follows as the documentation string. The @samp{/*} and @samp{*/} +delimiters that begin and end the comment are not part of the +documentation string. + +If the last line of the documentation string begins with the keyword +@samp{usage:}, the rest of the line is treated as the argument list +for documentation purposes. This way, you can use different argument +names in the documentation string from the ones used in the C code. + +All the usual rules for documentation strings in Lisp code +(@pxref{Documentation Tips}) apply to C code documentation strings +too. @end table After the call to the @code{DEFUN} macro, you must write the argument -- cgit v1.2.1