Mercurial > emacs
comparison lispref/tips.texi @ 77642:63ebf0b1cf38
(Documentation Tips): Rearrange items to place the more important ones first.
Add an index entry for hyperlinks.
author | Eli Zaretskii <eliz@gnu.org> |
---|---|
date | Fri, 04 May 2007 13:20:03 +0000 |
parents | 55c9ef5f1559 |
children | 665e86db2a21 d7172f202ab8 |
comparison
equal
deleted
inserted
replaced
77641:01d54caeca94 | 77642:63ebf0b1cf38 |
---|---|
646 Don't limit the documentation string to one line; use as many lines as | 646 Don't limit the documentation string to one line; use as many lines as |
647 you need to explain the details of how to use the function or | 647 you need to explain the details of how to use the function or |
648 variable. Please use complete sentences for the rest of the text too. | 648 variable. Please use complete sentences for the rest of the text too. |
649 | 649 |
650 @item | 650 @item |
651 When the user tries to use a disabled command, Emacs displays just the | |
652 first paragraph of its documentation string---everything through the | |
653 first blank line. If you wish, you can choose which information to | |
654 include before the first blank line so as to make this display useful. | |
655 | |
656 @item | |
651 The first line should mention all the important arguments of the | 657 The first line should mention all the important arguments of the |
652 function, and should mention them in the order that they are written | 658 function, and should mention them in the order that they are written |
653 in a function call. If the function has many arguments, then it is | 659 in a function call. If the function has many arguments, then it is |
654 not feasible to mention them all in the first line; in that case, the | 660 not feasible to mention them all in the first line; in that case, the |
655 first line should mention the first few arguments, including the most | 661 first line should mention the first few arguments, including the most |
656 important arguments. | 662 important arguments. |
657 | 663 |
658 @item | 664 @item |
659 For consistency, phrase the verb in the first sentence of a function's | 665 When a function's documentation string mentions the value of an argument |
660 documentation string as an imperative---for instance, use ``Return the | 666 of the function, use the argument name in capital letters as if it were |
661 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' | 667 a name for that value. Thus, the documentation string of the function |
662 Usually it looks good to do likewise for the rest of the first | 668 @code{eval} refers to its second argument as @samp{FORM}, because the |
663 paragraph. Subsequent paragraphs usually look better if each sentence | 669 actual argument name is @code{form}: |
664 is indicative and has a proper subject. | 670 |
665 | 671 @example |
666 @item | 672 Evaluate FORM and return its value. |
667 Write documentation strings in the active voice, not the passive, and in | 673 @end example |
668 the present tense, not the future. For instance, use ``Return a list | 674 |
669 containing A and B.'' instead of ``A list containing A and B will be | 675 Also write metasyntactic variables in capital letters, such as when you |
670 returned.'' | 676 show the decomposition of a list or vector into subunits, some of which |
671 | 677 may vary. @samp{KEY} and @samp{VALUE} in the following example |
672 @item | 678 illustrate this practice: |
673 Avoid using the word ``cause'' (or its equivalents) unnecessarily. | 679 |
674 Instead of, ``Cause Emacs to display text in boldface,'' write just | 680 @example |
675 ``Display text in boldface.'' | 681 The argument TABLE should be an alist whose elements |
676 | 682 have the form (KEY . VALUE). Here, KEY is ... |
677 @item | 683 @end example |
678 When a command is meaningful only in a certain mode or situation, | 684 |
679 do mention that in the documentation string. For example, | 685 @item |
680 the documentation of @code{dired-find-file} is: | 686 Never change the case of a Lisp symbol when you mention it in a doc |
681 | 687 string. If the symbol's name is @code{foo}, write ``foo,'' not |
682 @example | 688 ``Foo'' (which is a different symbol). |
683 In Dired, visit the file or directory named on this line. | 689 |
684 @end example | 690 This might appear to contradict the policy of writing function |
691 argument values, but there is no real contradiction; the argument | |
692 @emph{value} is not the same thing as the @emph{symbol} which the | |
693 function uses to hold the value. | |
694 | |
695 If this puts a lower-case letter at the beginning of a sentence | |
696 and that annoys you, rewrite the sentence so that the symbol | |
697 is not at the start of it. | |
685 | 698 |
686 @item | 699 @item |
687 Do not start or end a documentation string with whitespace. | 700 Do not start or end a documentation string with whitespace. |
688 | 701 |
689 @item | 702 @item |
690 @strong{Do not} indent subsequent lines of a documentation string so | 703 @strong{Do not} indent subsequent lines of a documentation string so |
691 that the text is lined up in the source code with the text of the first | 704 that the text is lined up in the source code with the text of the first |
692 line. This looks nice in the source code, but looks bizarre when users | 705 line. This looks nice in the source code, but looks bizarre when users |
693 view the documentation. Remember that the indentation before the | 706 view the documentation. Remember that the indentation before the |
694 starting double-quote is not part of the string! | 707 starting double-quote is not part of the string! |
695 | |
696 @item | |
697 When the user tries to use a disabled command, Emacs displays just the | |
698 first paragraph of its documentation string---everything through the | |
699 first blank line. If you wish, you can choose which information to | |
700 include before the first blank line so as to make this display useful. | |
701 | |
702 @item | |
703 When you define a variable that users ought to set interactively, you | |
704 normally should use @code{defcustom}. However, if for some reason you | |
705 use @code{defvar} instead, start the doc string with a @samp{*}. | |
706 @xref{Defining Variables}. | |
707 | |
708 @item | |
709 The documentation string for a variable that is a yes-or-no flag should | |
710 start with words such as ``Non-nil means,'' to make it clear that | |
711 all non-@code{nil} values are equivalent and indicate explicitly what | |
712 @code{nil} and non-@code{nil} mean. | |
713 | |
714 @item | |
715 The documentation string for a function that is a yes-or-no predicate | |
716 should start with words such as ``Return t if,'' to indicate | |
717 explicitly what constitutes ``truth.'' The word ``return'' avoids | |
718 starting the sentence with lower-case ``t,'' which could be somewhat | |
719 distracting. | |
720 | |
721 @item | |
722 When a function's documentation string mentions the value of an argument | |
723 of the function, use the argument name in capital letters as if it were | |
724 a name for that value. Thus, the documentation string of the function | |
725 @code{eval} refers to its second argument as @samp{FORM}, because the | |
726 actual argument name is @code{form}: | |
727 | |
728 @example | |
729 Evaluate FORM and return its value. | |
730 @end example | |
731 | |
732 Also write metasyntactic variables in capital letters, such as when you | |
733 show the decomposition of a list or vector into subunits, some of which | |
734 may vary. @samp{KEY} and @samp{VALUE} in the following example | |
735 illustrate this practice: | |
736 | |
737 @example | |
738 The argument TABLE should be an alist whose elements | |
739 have the form (KEY . VALUE). Here, KEY is ... | |
740 @end example | |
741 | |
742 @item | |
743 Never change the case of a Lisp symbol when you mention it in a doc | |
744 string. If the symbol's name is @code{foo}, write ``foo,'' not | |
745 ``Foo'' (which is a different symbol). | |
746 | |
747 This might appear to contradict the policy of writing function | |
748 argument values, but there is no real contradiction; the argument | |
749 @emph{value} is not the same thing as the @emph{symbol} which the | |
750 function uses to hold the value. | |
751 | |
752 If this puts a lower-case letter at the beginning of a sentence | |
753 and that annoys you, rewrite the sentence so that the symbol | |
754 is not at the start of it. | |
755 | |
756 @item | |
757 If a line in a documentation string begins with an open-parenthesis, | |
758 write a backslash before the open-parenthesis, like this: | |
759 | |
760 @example | |
761 The argument FOO can be either a number | |
762 \(a buffer position) or a string (a file name). | |
763 @end example | |
764 | |
765 This prevents the open-parenthesis from being treated as the start of a | |
766 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). | |
767 | 708 |
768 @anchor{Docstring hyperlinks} | 709 @anchor{Docstring hyperlinks} |
769 @item | 710 @item |
770 @iftex | 711 @iftex |
771 When a documentation string refers to a Lisp symbol, write it as it | 712 When a documentation string refers to a Lisp symbol, write it as it |
779 around it. For example: @samp{lambda}. There are two exceptions: write | 720 around it. For example: @samp{lambda}. There are two exceptions: write |
780 t and nil without single-quotes. (In this manual, we use a different | 721 t and nil without single-quotes. (In this manual, we use a different |
781 convention, with single-quotes for all symbols.) | 722 convention, with single-quotes for all symbols.) |
782 @end ifnottex | 723 @end ifnottex |
783 | 724 |
725 @cindex hyperlinks in documentation strings | |
784 Help mode automatically creates a hyperlink when a documentation string | 726 Help mode automatically creates a hyperlink when a documentation string |
785 uses a symbol name inside single quotes, if the symbol has either a | 727 uses a symbol name inside single quotes, if the symbol has either a |
786 function or a variable definition. You do not need to do anything | 728 function or a variable definition. You do not need to do anything |
787 special to make use of this feature. However, when a symbol has both a | 729 special to make use of this feature. However, when a symbol has both a |
788 function definition and a variable definition, and you want to refer to | 730 function definition and a variable definition, and you want to refer to |
861 | 803 |
862 It is not practical to use @samp{\\[@dots{}]} very many times, because | 804 It is not practical to use @samp{\\[@dots{}]} very many times, because |
863 display of the documentation string will become slow. So use this to | 805 display of the documentation string will become slow. So use this to |
864 describe the most important commands in your major mode, and then use | 806 describe the most important commands in your major mode, and then use |
865 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap. | 807 @samp{\\@{@dots{}@}} to display the rest of the mode's keymap. |
808 | |
809 @item | |
810 For consistency, phrase the verb in the first sentence of a function's | |
811 documentation string as an imperative---for instance, use ``Return the | |
812 cons of A and B.'' in preference to ``Returns the cons of A and B@.'' | |
813 Usually it looks good to do likewise for the rest of the first | |
814 paragraph. Subsequent paragraphs usually look better if each sentence | |
815 is indicative and has a proper subject. | |
816 | |
817 @item | |
818 The documentation string for a function that is a yes-or-no predicate | |
819 should start with words such as ``Return t if,'' to indicate | |
820 explicitly what constitutes ``truth.'' The word ``return'' avoids | |
821 starting the sentence with lower-case ``t,'' which could be somewhat | |
822 distracting. | |
823 | |
824 @item | |
825 If a line in a documentation string begins with an open-parenthesis, | |
826 write a backslash before the open-parenthesis, like this: | |
827 | |
828 @example | |
829 The argument FOO can be either a number | |
830 \(a buffer position) or a string (a file name). | |
831 @end example | |
832 | |
833 This prevents the open-parenthesis from being treated as the start of a | |
834 defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}). | |
835 | |
836 @item | |
837 Write documentation strings in the active voice, not the passive, and in | |
838 the present tense, not the future. For instance, use ``Return a list | |
839 containing A and B.'' instead of ``A list containing A and B will be | |
840 returned.'' | |
841 | |
842 @item | |
843 Avoid using the word ``cause'' (or its equivalents) unnecessarily. | |
844 Instead of, ``Cause Emacs to display text in boldface,'' write just | |
845 ``Display text in boldface.'' | |
846 | |
847 @item | |
848 When a command is meaningful only in a certain mode or situation, | |
849 do mention that in the documentation string. For example, | |
850 the documentation of @code{dired-find-file} is: | |
851 | |
852 @example | |
853 In Dired, visit the file or directory named on this line. | |
854 @end example | |
855 | |
856 @item | |
857 When you define a variable that users ought to set interactively, you | |
858 normally should use @code{defcustom}. However, if for some reason you | |
859 use @code{defvar} instead, start the doc string with a @samp{*}. | |
860 @xref{Defining Variables}. | |
861 | |
862 @item | |
863 The documentation string for a variable that is a yes-or-no flag should | |
864 start with words such as ``Non-nil means,'' to make it clear that | |
865 all non-@code{nil} values are equivalent and indicate explicitly what | |
866 @code{nil} and non-@code{nil} mean. | |
866 @end itemize | 867 @end itemize |
867 | 868 |
868 @node Comment Tips | 869 @node Comment Tips |
869 @section Tips on Writing Comments | 870 @section Tips on Writing Comments |
870 @cindex comments, Lisp convention for | 871 @cindex comments, Lisp convention for |