From aa5dbf7b628a88e6016dd41947a7fe7180b6eec6 Mon Sep 17 00:00:00 2001 From: "Richard M. Stallman" Date: Tue, 13 Nov 2001 02:20:53 +0000 Subject: [PATCH] Say what questions first line of doc string should answer. --- lispref/tips.texi | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/lispref/tips.texi b/lispref/tips.texi index 1ecd312f4b5..aafd1436c0b 100644 --- a/lispref/tips.texi +++ b/lispref/tips.texi @@ -489,9 +489,13 @@ apropos} displays just the first line, and if that line's contents don't stand on their own, the result looks bad. In particular, start the first line with a capital letter and end with a period. -The documentation string is not limited to one line; use as many lines -as you need to explain the details of how to use the function or -variable. Please use complete sentences in the additional lines. +For a function, the first line should briefly answer the question, +``What does this function do?'' For a variable, the first line should +briefly answer the question, ``What does this value mean?'' + +Don't limit the documentation string to one line; use as many lines as +you need to explain the details of how to use the function or +variable. Please use complete sentences for the rest of the text too. @item For consistency, phrase the verb in the first sentence of a function's -- 2.39.2