Mercurial > emacs
comparison lispref/tips.texi @ 26696:ef5e7bbe6f19
Current version from /gd/gnu/elisp.
author | Dave Love <fx@gnu.org> |
---|---|
date | Fri, 03 Dec 1999 19:11:12 +0000 |
parents | df0efa93750b |
children | f6b52258db6a |
comparison
equal
deleted
inserted
replaced
26695:778a88ba7c10 | 26696:ef5e7bbe6f19 |
---|---|
421 | 421 |
422 @item | 422 @item |
423 An internal variable or subroutine of a Lisp program might as well have | 423 An internal variable or subroutine of a Lisp program might as well have |
424 a documentation string. In earlier Emacs versions, you could save space | 424 a documentation string. In earlier Emacs versions, you could save space |
425 by using a comment instead of a documentation string, but that is no | 425 by using a comment instead of a documentation string, but that is no |
426 longer the case. | 426 longer the case---documentation strings now take up very little space in |
427 a running Emacs. | |
427 | 428 |
428 @item | 429 @item |
429 The first line of the documentation string should consist of one or two | 430 The first line of the documentation string should consist of one or two |
430 complete sentences that stand on their own as a summary. @kbd{M-x | 431 complete sentences that stand on their own as a summary. @kbd{M-x |
431 apropos} displays just the first line, and if it doesn't stand on its | 432 apropos} displays just the first line, and if that line's contents don't |
432 own, the result looks bad. In particular, start the first line with a | 433 stand on their own, the result looks bad. In particular, start the |
433 capital letter and end with a period. | 434 first line with a capital letter and end with a period. |
434 | 435 |
435 The documentation string can have additional lines that expand on the | 436 The documentation string is not limited to one line; use as many lines |
436 details of how to use the function or variable. The additional lines | 437 as you need to explain the details of how to use the function or |
437 should be made up of complete sentences also, but they may be filled if | 438 variable. Please use complete sentences in the additional lines. |
438 that looks good. | |
439 | 439 |
440 @item | 440 @item |
441 For consistency, phrase the verb in the first sentence of a function's | 441 For consistency, phrase the verb in the first sentence of a function's |
442 documentation string as an imperative--for instance, use ``Return the | 442 documentation string as an imperative--for instance, use ``Return the |
443 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' | 443 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' |
455 Avoid using the word ``cause'' (or its equivalents) unnecessarily. | 455 Avoid using the word ``cause'' (or its equivalents) unnecessarily. |
456 Instead of, ``Cause Emacs to display text in boldface,'' write just | 456 Instead of, ``Cause Emacs to display text in boldface,'' write just |
457 ``Display text in boldface.'' | 457 ``Display text in boldface.'' |
458 | 458 |
459 @item | 459 @item |
460 When a command is meaningful only in a certain mode or situation, | |
461 do mention that in the documentation string. For example, | |
462 the documentation of @code{dired-find-file} is: | |
463 | |
464 @example | |
465 In Dired, visit the file or directory named on this line. | |
466 @end example | |
467 | |
468 @item | |
460 Do not start or end a documentation string with whitespace. | 469 Do not start or end a documentation string with whitespace. |
461 | 470 |
462 @item | 471 @item |
463 Format the documentation string so that it fits in an Emacs window on an | 472 Format the documentation string so that it fits in an Emacs window on an |
464 80-column screen. It is a good idea for most lines to be no wider than | 473 80-column screen. It is a good idea for most lines to be no wider than |
465 60 characters. The first line can be wider if necessary to fit the | 474 60 characters. The first line should not be wider than 67 characters |
466 information that ought to be there. | 475 or it will look bad in the output of @code{apropos}. |
467 | 476 |
468 However, rather than simply filling the entire documentation string, you | 477 You can fill the text if that looks good. However, rather than blindly |
469 can make it much more readable by choosing line breaks with care. | 478 filling the entire documentation string, you can often make it much more |
470 Use blank lines between topics if the documentation string is long. | 479 readable by choosing certain line breaks with care. Use blank lines |
480 between topics if the documentation string is long. | |
471 | 481 |
472 @item | 482 @item |
473 @strong{Do not} indent subsequent lines of a documentation string so | 483 @strong{Do not} indent subsequent lines of a documentation string so |
474 that the text is lined up in the source code with the text of the first | 484 that the text is lined up in the source code with the text of the first |
475 line. This looks nice in the source code, but looks bizarre when users | 485 line. This looks nice in the source code, but looks bizarre when users |
497 | 507 |
498 @item | 508 @item |
499 When a function's documentation string mentions the value of an argument | 509 When a function's documentation string mentions the value of an argument |
500 of the function, use the argument name in capital letters as if it were | 510 of the function, use the argument name in capital letters as if it were |
501 a name for that value. Thus, the documentation string of the function | 511 a name for that value. Thus, the documentation string of the function |
502 @code{/} refers to its second argument as @samp{DIVISOR}, because the | 512 @code{eval} refers to its second argument as @samp{FORM}, because the |
503 actual argument name is @code{divisor}. | 513 actual argument name is @code{form}: |
504 | 514 |
505 Also use all caps for metasyntactic variables, such as when you show | 515 @example |
506 the decomposition of a list or vector into subunits, some of which may | 516 Evaluate FORM and return its value. |
507 vary. @samp{KEY} and @samp{VALUE} in the following example | 517 @end example |
518 | |
519 Also write metasyntactic variables in capital letters, such as when you | |
520 show the decomposition of a list or vector into subunits, some of which | |
521 may vary. @samp{KEY} and @samp{VALUE} in the following example | |
508 illustrate this practice: | 522 illustrate this practice: |
509 | 523 |
510 @example | 524 @example |
511 The argument TABLE should be an alist whose elements | 525 The argument TABLE should be an alist whose elements |
512 have the form (KEY . VALUE). Here, KEY is ... | 526 have the form (KEY . VALUE). Here, KEY is ... |
513 @end example | 527 @end example |
528 | |
529 @item | |
530 If a line in a documentation string begins with an open-parenthesis, | |
531 write a backslash before the open-parenthesis, like this: | |
532 | |
533 @example | |
534 The argument FOO can be either a number | |
535 \(a buffer position) or a string (a file name). | |
536 @end example | |
537 | |
538 This prevents the open-parenthesis from being treated as the start of a | |
539 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). | |
514 | 540 |
515 @item | 541 @item |
516 @iftex | 542 @iftex |
517 When a documentation string refers to a Lisp symbol, write it as it | 543 When a documentation string refers to a Lisp symbol, write it as it |
518 would be printed (which usually means in lower case), with single-quotes | 544 would be printed (which usually means in lower case), with single-quotes |
632 ;; update mode line | 658 ;; update mode line |
633 (force-mode-line-update))) | 659 (force-mode-line-update))) |
634 @end group | 660 @end group |
635 @end smallexample | 661 @end smallexample |
636 | 662 |
663 We also normally use two semicolons for comments outside functions. | |
664 | |
665 @smallexample | |
666 @group | |
667 ;; This Lisp code is run in Emacs | |
668 ;; when it is to operate as a server | |
669 ;; for other processes. | |
670 @end group | |
671 @end smallexample | |
672 | |
637 Every function that has no documentation string (presumably one that is | 673 Every function that has no documentation string (presumably one that is |
638 used only internally within the package it belongs to), should have | 674 used only internally within the package it belongs to), should instead |
639 instead a two-semicolon comment right before the function, explaining | 675 have a two-semicolon comment right before the function, explaining what |
640 what the function does and how to call it properly. Explain precisely | 676 the function does and how to call it properly. Explain precisely what |
641 what each argument means and how the function interprets its possible | 677 each argument means and how the function interprets its possible values. |
642 values. | |
643 | 678 |
644 @item ;;; | 679 @item ;;; |
645 Comments that start with three semicolons, @samp{;;;}, should start at | 680 Comments that start with three semicolons, @samp{;;;}, should start at |
646 the left margin. Such comments are used outside function definitions to | 681 the left margin. These are used, occasionally, for comments within |
647 make general statements explaining the design principles of the program. | 682 functions that should start at the margin. We also use them sometimes |
648 For example: | 683 for comments that are between functions---whether to use two or three |
649 | 684 semicolons there is a matter of style. |
650 @smallexample | |
651 @group | |
652 ;;; This Lisp code is run in Emacs | |
653 ;;; when it is to operate as a server | |
654 ;;; for other processes. | |
655 @end group | |
656 @end smallexample | |
657 | 685 |
658 Another use for triple-semicolon comments is for commenting out lines | 686 Another use for triple-semicolon comments is for commenting out lines |
659 within a function. We use triple-semicolons for this precisely so that | 687 within a function. We use three semicolons for this precisely so that |
660 they remain at the left margin. | 688 they remain at the left margin. |
661 | 689 |
662 @smallexample | 690 @smallexample |
663 (defun foo (a) | 691 (defun foo (a) |
664 ;;; This is no longer necessary. | 692 ;;; This is no longer necessary. |
797 @samp{Keywords} header comment lines. Use the others if they are | 825 @samp{Keywords} header comment lines. Use the others if they are |
798 appropriate. You can also put in header lines with other header | 826 appropriate. You can also put in header lines with other header |
799 names---they have no standard meanings, so they can't do any harm. | 827 names---they have no standard meanings, so they can't do any harm. |
800 | 828 |
801 We use additional stylized comments to subdivide the contents of the | 829 We use additional stylized comments to subdivide the contents of the |
802 library file. Here is a table of them: | 830 library file. These should be separated by blank lines from anything |
831 else. Here is a table of them: | |
803 | 832 |
804 @table @samp | 833 @table @samp |
805 @item ;;; Commentary: | 834 @item ;;; Commentary: |
806 This begins introductory comments that explain how the library works. | 835 This begins introductory comments that explain how the library works. |
807 It should come right after the copying permissions, terminated by a | 836 It should come right after the copying permissions, terminated by a |
813 This has been used in some files in place of @samp{;;; Commentary:}, | 842 This has been used in some files in place of @samp{;;; Commentary:}, |
814 but @samp{;;; Commentary:} is preferred. | 843 but @samp{;;; Commentary:} is preferred. |
815 | 844 |
816 @item ;;; Change Log: | 845 @item ;;; Change Log: |
817 This begins change log information stored in the library file (if you | 846 This begins change log information stored in the library file (if you |
818 store the change history there). For most of the Lisp | 847 store the change history there). For Lisp files distributed with Emacs, |
819 files distributed with Emacs, the change history is kept in the file | 848 the change history is kept in the file @file{ChangeLog} and not in the |
820 @file{ChangeLog} and not in the source file at all; these files do | 849 source file at all; these files generally do not have a @samp{;;; Change |
821 not have a @samp{;;; Change Log:} line. @samp{History} is an | 850 Log:} line. @samp{History} is an alternative to @samp{Change Log}. |
822 alternative to @samp{Change Log}. | |
823 | 851 |
824 @item ;;; Code: | 852 @item ;;; Code: |
825 This begins the actual code of the program. | 853 This begins the actual code of the program. |
826 | 854 |
827 @item ;;; @var{filename} ends here | 855 @item ;;; @var{filename} ends here |