bug#9130: 23.3; Lisp mode doc string enhancment

bug#9130: 23.3; Lisp mode doc string enhancment

[Robert Brown]

Here is a change that enhances Lisp mode fontification to handle
documentation of the form

    (:documentation "the doc string")

These kinds of documentation forms are used in Common Lisp code for CLOS
class and slot documentation.

To apply the patch, replace lisp-font-lock-syntactic-face-function in
share/emacs/23.3/lisp/emacs-lisp/lisp-mode.el with the three functions
below:

(defun string-in-doc-position-p (state)
  (let* ((listbeg (nth 1 state))
         (firstsym (and listbeg
                        (save-excursion
                          (goto-char listbeg)
                          (and (looking-at "([ \t\n]*\\(\\(\\sw\\|\\s_\\)+\\)")
                               (match-string 1)))))
         (docelt (and firstsym (get (intern-soft firstsym)
                                    lisp-doc-string-elt-property))))
    (and docelt
         ;; It's a string in a form that can have a docstring.
         ;; Check whether it's in docstring position.
         (save-excursion
           (when (functionp docelt)
             (goto-char (match-end 1))
             (setq docelt (funcall docelt)))
           (goto-char listbeg)
           (forward-char 1)
           (condition-case nil
               (while (and (> docelt 0) (< (point) startpos)
                           (progn (forward-sexp 1) t))
                 (setq docelt (1- docelt)))
             (error nil))
           (and (zerop docelt) (<= (point) startpos)
                (progn (forward-comment (point-max)) t)
                (= (point) (nth 8 state)))))))

(defun string-after-documentation-keyword-p (state)
  (and (nth 1 state)                    ; we are inside a Lisp form
       (let ((startpos (nth 8 state)))
         (and startpos
              (let ((ok nil)
                    (prevsym (save-excursion
                               (goto-char startpos)
                               (condition-case nil
                                   (progn (backward-sexp 1) (setf ok t))
                                 (error nil))
                               (and ok
                                    (looking-at "\\(\\sw+\\)")
                                    (match-string 1)))))
                (equal prevsym ":documentation"))))))

(defun lisp-font-lock-syntactic-face-function (state)
  (if (nth 3 state)
      ;; This might be a (doc)string or a |...| symbol.
      (let ((startpos (nth 8 state)))
        (if (eq (char-after startpos) ?|)
            ;; This is not a string, but a |...| symbol.
            nil
          (if (or (string-in-doc-position-p state)
                  (string-after-documentation-keyword-p state))
              font-lock-doc-face
            font-lock-string-face)))
    font-lock-comment-face))



In GNU Emacs 23.3.1 (x86_64-unknown-linux-gnu)
 of 2011-07-15 on paradicsom.nyc.corp.google.com
configured using `configure  '--prefix' '/local/software/package/emacs-23.3.1' '--without-x''

Important settings:
  value of $LC_ALL: nil
  value of $LC_COLLATE: C
  value of $LC_CTYPE: nil
  value of $LC_MESSAGES: nil
  value of $LC_MONETARY: C
  value of $LC_NUMERIC: C
  value of $LC_TIME: C
  value of $LANG: en_US.UTF-8
  value of $XMODIFIERS: nil
  locale-coding-system: utf-8-unix
  default enable-multibyte-characters: t

Major mode: Emacs-Lisp

Minor modes in effect:
  file-name-shadow-mode: t
  global-font-lock-mode: t
  font-lock-mode: t
  auto-encryption-mode: t
  auto-compression-mode: t
  line-number-mode: t

Recent input:
ESC [ > 1 ; 2 3 0 5 ; 0 c C-x C-f . e m a c s RET C-v 
C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v ESC v ESC 
v ESC v ESC v ESC v ESC v C-v C-v C-v C-v C-a C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-l C-v C-v C-v ESC v ESC v ESC v ESC v ESC v ESC v 
ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC 
v ESC v ESC v C-v C-l C-u C-u C-n C-n C-n DEL C-x SPC 
SPC C-a C-x C-s C-v C-x C-s C-v C-v C-v C-v ESC v C-v 
C-n C-n C-n C-n C-n C-n C-n C-n C-l C-u C-p C-p C-p 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-l ESC 
x r e p o r t - e m a c s - b u g RET

Recent messages:
("emacs")
Loading /local/software/source-trees/emacs-jabber/jabber-autoloads.el (source)...done
call-interactively: Beginning of buffer [3 times]
Saving file /home/brown/.emacs...
Wrote /home/brown/.emacs
(No changes need to be saved)

Load-path shadows:
/local/software/source-trees/cc-mode/cc-fonts hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-fonts
/local/software/source-trees/cc-mode/cc-align hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-align
/local/software/source-trees/cc-mode/cc-menus hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-menus
/local/software/source-trees/cc-mode/cc-engine hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-engine
/local/software/source-trees/cc-mode/cc-mode hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-mode
/local/software/source-trees/cc-mode/cc-awk hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-awk
/local/software/source-trees/cc-mode/cc-defs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-defs
/local/software/source-trees/cc-mode/cc-vars hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-vars
/local/software/source-trees/cc-mode/cc-styles hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-styles
/local/software/source-trees/cc-mode/cc-bytecomp hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-bytecomp
/local/software/source-trees/cc-mode/cc-compat hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-compat
/local/software/source-trees/cc-mode/cc-cmds hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-cmds
/local/software/source-trees/cc-mode/cc-langs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-langs
/local/software/package/org-5.13e/org-publish hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-publish
/local/software/package/org-5.13e/org hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org
/local/software/package/org-5.13e/org-install hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-install
/local/software/package/org-5.13e/org-mouse hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-mouse

Features:
(shadow sort mail-extr message ecomplete rfc822 mml easymenu mml-sec
password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
time-date mm-util mail-prsvr gmm-utils wid-edit mailheader canlock sha1
hex-util hashcash mail-utils warnings emacsbug uniquify advice help-fns
advice-preload slime-autoloads regexp-opt cl cl-19 ediff-hook vc-hooks
lisp-float-type lisp-mode register page menu-bar rfn-eshadow timer
jit-lock font-lock syntax facemenu font-core frame cham georgian
utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
japanese hebrew greek romanian slovak czech european ethiopic indian
cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
loaddefs button minibuffer faces cus-face files text-properties overlay
md5 base64 format env code-pages mule custom widget
hashtable-print-readable backquote make-network-process multi-tty emacs)

bug#9130: 23.3; Lisp mode doc string enhancment

[Stefan Monnier]

severity 9130 wishlist
tags 9130 patch
thanks

> Here is a change that enhances Lisp mode fontification to handle
> documentation of the form

>     (:documentation "the doc string")

Thanks.  That looks like a useful addition.  Could you try and make it
an actual patch (as output by `diff' and friends), also could you also
make sure your code uses a proper prefix ("lisp-") for all the functions
it defines, and finally could you make sure it's only enabled when it's
useful (I don't think we support such :documentation thingies in Elisp
(tho maybe EIEIO does) so it should only be enabled in lisp-mode but
not in emacs-lisp-mode).

There's time for that: we're in feature freeze for Emacs-24.1, so we
won't install such a change before early next year.


        Stefan


> These kinds of documentation forms are used in Common Lisp code for CLOS
> class and slot documentation.

> To apply the patch, replace lisp-font-lock-syntactic-face-function in
> share/emacs/23.3/lisp/emacs-lisp/lisp-mode.el with the three functions
> below:

> (defun string-in-doc-position-p (state)
>   (let* ((listbeg (nth 1 state))
>          (firstsym (and listbeg
>                         (save-excursion
>                           (goto-char listbeg)
>                           (and (looking-at "([ \t\n]*\\(\\(\\sw\\|\\s_\\)+\\)")
>                                (match-string 1)))))
>          (docelt (and firstsym (get (intern-soft firstsym)
>                                     lisp-doc-string-elt-property))))
>     (and docelt
>          ;; It's a string in a form that can have a docstring.
>          ;; Check whether it's in docstring position.
>          (save-excursion
>            (when (functionp docelt)
>              (goto-char (match-end 1))
>              (setq docelt (funcall docelt)))
>            (goto-char listbeg)
>            (forward-char 1)
>            (condition-case nil
>                (while (and (> docelt 0) (< (point) startpos)
>                            (progn (forward-sexp 1) t))
>                  (setq docelt (1- docelt)))
>              (error nil))
>            (and (zerop docelt) (<= (point) startpos)
>                 (progn (forward-comment (point-max)) t)
>                 (= (point) (nth 8 state)))))))

> (defun string-after-documentation-keyword-p (state)
>   (and (nth 1 state)                    ; we are inside a Lisp form
>        (let ((startpos (nth 8 state)))
>          (and startpos
>               (let ((ok nil)
>                     (prevsym (save-excursion
>                                (goto-char startpos)
>                                (condition-case nil
>                                    (progn (backward-sexp 1) (setf ok t))
>                                  (error nil))
>                                (and ok
>                                     (looking-at "\\(\\sw+\\)")
>                                     (match-string 1)))))
>                 (equal prevsym ":documentation"))))))

> (defun lisp-font-lock-syntactic-face-function (state)
>   (if (nth 3 state)
>       ;; This might be a (doc)string or a |...| symbol.
>       (let ((startpos (nth 8 state)))
>         (if (eq (char-after startpos) ?|)
>             ;; This is not a string, but a |...| symbol.
>             nil
>           (if (or (string-in-doc-position-p state)
>                   (string-after-documentation-keyword-p state))
>               font-lock-doc-face
>             font-lock-string-face)))
>     font-lock-comment-face))



> In GNU Emacs 23.3.1 (x86_64-unknown-linux-gnu)
>  of 2011-07-15 on paradicsom.nyc.corp.google.com
> configured using `configure  '--prefix' '/local/software/package/emacs-23.3.1' '--without-x''

> Important settings:
>   value of $LC_ALL: nil
>   value of $LC_COLLATE: C
>   value of $LC_CTYPE: nil
>   value of $LC_MESSAGES: nil
>   value of $LC_MONETARY: C
>   value of $LC_NUMERIC: C
>   value of $LC_TIME: C
>   value of $LANG: en_US.UTF-8
>   value of $XMODIFIERS: nil
>   locale-coding-system: utf-8-unix
>   default enable-multibyte-characters: t

> Major mode: Emacs-Lisp

> Minor modes in effect:
>   file-name-shadow-mode: t
>   global-font-lock-mode: t
>   font-lock-mode: t
>   auto-encryption-mode: t
>   auto-compression-mode: t
>   line-number-mode: t

> Recent input:
> ESC [ > 1 ; 2 3 0 5 ; 0 c C-x C-f . e m a c s RET C-v 
> C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v ESC v ESC 
> v ESC v ESC v ESC v ESC v C-v C-v C-v C-v C-a C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-l C-v C-v C-v ESC v ESC v ESC v ESC v ESC v ESC v 
> ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC 
> v ESC v ESC v C-v C-l C-u C-u C-n C-n C-n DEL C-x SPC 
> SPC C-a C-x C-s C-v C-x C-s C-v C-v C-v C-v ESC v C-v 
> C-n C-n C-n C-n C-n C-n C-n C-n C-l C-u C-p C-p C-p 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n 
> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-l ESC 
> x r e p o r t - e m a c s - b u g RET

> Recent messages:
> ("emacs")
> Loading /local/software/source-trees/emacs-jabber/jabber-autoloads.el (source)...done
> call-interactively: Beginning of buffer [3 times]
> Saving file /home/brown/.emacs...
> Wrote /home/brown/.emacs
> (No changes need to be saved)

> Load-path shadows:
> /local/software/source-trees/cc-mode/cc-fonts hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-fonts
> /local/software/source-trees/cc-mode/cc-align hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-align
> /local/software/source-trees/cc-mode/cc-menus hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-menus
> /local/software/source-trees/cc-mode/cc-engine hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-engine
> /local/software/source-trees/cc-mode/cc-mode hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-mode
> /local/software/source-trees/cc-mode/cc-awk hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-awk
> /local/software/source-trees/cc-mode/cc-defs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-defs
> /local/software/source-trees/cc-mode/cc-vars hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-vars
> /local/software/source-trees/cc-mode/cc-styles hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-styles
> /local/software/source-trees/cc-mode/cc-bytecomp hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-bytecomp
> /local/software/source-trees/cc-mode/cc-compat hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-compat
> /local/software/source-trees/cc-mode/cc-cmds hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-cmds
> /local/software/source-trees/cc-mode/cc-langs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-langs
> /local/software/package/org-5.13e/org-publish hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-publish
> /local/software/package/org-5.13e/org hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org
> /local/software/package/org-5.13e/org-install hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-install
> /local/software/package/org-5.13e/org-mouse hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-mouse

> Features:
> (shadow sort mail-extr message ecomplete rfc822 mml easymenu mml-sec
> password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
> rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
> time-date mm-util mail-prsvr gmm-utils wid-edit mailheader canlock sha1
> hex-util hashcash mail-utils warnings emacsbug uniquify advice help-fns
> advice-preload slime-autoloads regexp-opt cl cl-19 ediff-hook vc-hooks
> lisp-float-type lisp-mode register page menu-bar rfn-eshadow timer
> jit-lock font-lock syntax facemenu font-core frame cham georgian
> utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
> japanese hebrew greek romanian slovak czech european ethiopic indian
> cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
> loaddefs button minibuffer faces cus-face files text-properties overlay
> md5 base64 format env code-pages mule custom widget
> hashtable-print-readable backquote make-network-process multi-tty emacs)

bug#9130: 23.3; Lisp mode doc string enhancment

[Robert Brown]

[-- Attachment #1: Type: text/plain, Size: 9378 bytes --]

I have converted the change into a patch made with diff and
have included it as an attachment.  The patch is relative to
Emacs version 24.3.

EIEIO supports defclass with :documentation strings, so I
think the detection of such strings should be active in both
emacs-lisp-mode and lisp-mode.

Bob


On Tue, Aug 2, 2011 at 4:01 PM, Stefan Monnier <monnier@iro.umontreal.ca> wrote:
> severity 9130 wishlist
> tags 9130 patch
> thanks
>
>> Here is a change that enhances Lisp mode fontification to handle
>> documentation of the form
>
>>     (:documentation "the doc string")
>
> Thanks.  That looks like a useful addition.  Could you try and make it
> an actual patch (as output by `diff' and friends), also could you also
> make sure your code uses a proper prefix ("lisp-") for all the functions
> it defines, and finally could you make sure it's only enabled when it's
> useful (I don't think we support such :documentation thingies in Elisp
> (tho maybe EIEIO does) so it should only be enabled in lisp-mode but
> not in emacs-lisp-mode).
>
> There's time for that: we're in feature freeze for Emacs-24.1, so we
> won't install such a change before early next year.
>
>
>         Stefan
>
>
>> These kinds of documentation forms are used in Common Lisp code for CLOS
>> class and slot documentation.
>
>> To apply the patch, replace lisp-font-lock-syntactic-face-function in
>> share/emacs/23.3/lisp/emacs-lisp/lisp-mode.el with the three functions
>> below:
>
>> (defun string-in-doc-position-p (state)
>>   (let* ((listbeg (nth 1 state))
>>          (firstsym (and listbeg
>>                         (save-excursion
>>                           (goto-char listbeg)
>>                           (and (looking-at "([ \t\n]*\\(\\(\\sw\\|\\s_\\)+\\)")
>>                                (match-string 1)))))
>>          (docelt (and firstsym (get (intern-soft firstsym)
>>                                     lisp-doc-string-elt-property))))
>>     (and docelt
>>          ;; It's a string in a form that can have a docstring.
>>          ;; Check whether it's in docstring position.
>>          (save-excursion
>>            (when (functionp docelt)
>>              (goto-char (match-end 1))
>>              (setq docelt (funcall docelt)))
>>            (goto-char listbeg)
>>            (forward-char 1)
>>            (condition-case nil
>>                (while (and (> docelt 0) (< (point) startpos)
>>                            (progn (forward-sexp 1) t))
>>                  (setq docelt (1- docelt)))
>>              (error nil))
>>            (and (zerop docelt) (<= (point) startpos)
>>                 (progn (forward-comment (point-max)) t)
>>                 (= (point) (nth 8 state)))))))
>
>> (defun string-after-documentation-keyword-p (state)
>>   (and (nth 1 state)                    ; we are inside a Lisp form
>>        (let ((startpos (nth 8 state)))
>>          (and startpos
>>               (let ((ok nil)
>>                     (prevsym (save-excursion
>>                                (goto-char startpos)
>>                                (condition-case nil
>>                                    (progn (backward-sexp 1) (setf ok t))
>>                                  (error nil))
>>                                (and ok
>>                                     (looking-at "\\(\\sw+\\)")
>>                                     (match-string 1)))))
>>                 (equal prevsym ":documentation"))))))
>
>> (defun lisp-font-lock-syntactic-face-function (state)
>>   (if (nth 3 state)
>>       ;; This might be a (doc)string or a |...| symbol.
>>       (let ((startpos (nth 8 state)))
>>         (if (eq (char-after startpos) ?|)
>>             ;; This is not a string, but a |...| symbol.
>>             nil
>>           (if (or (string-in-doc-position-p state)
>>                   (string-after-documentation-keyword-p state))
>>               font-lock-doc-face
>>             font-lock-string-face)))
>>     font-lock-comment-face))
>
>
>
>> In GNU Emacs 23.3.1 (x86_64-unknown-linux-gnu)
>>  of 2011-07-15 on paradicsom.nyc.corp.google.com
>> configured using `configure  '--prefix' '/local/software/package/emacs-23.3.1' '--without-x''
>
>> Important settings:
>>   value of $LC_ALL: nil
>>   value of $LC_COLLATE: C
>>   value of $LC_CTYPE: nil
>>   value of $LC_MESSAGES: nil
>>   value of $LC_MONETARY: C
>>   value of $LC_NUMERIC: C
>>   value of $LC_TIME: C
>>   value of $LANG: en_US.UTF-8
>>   value of $XMODIFIERS: nil
>>   locale-coding-system: utf-8-unix
>>   default enable-multibyte-characters: t
>
>> Major mode: Emacs-Lisp
>
>> Minor modes in effect:
>>   file-name-shadow-mode: t
>>   global-font-lock-mode: t
>>   font-lock-mode: t
>>   auto-encryption-mode: t
>>   auto-compression-mode: t
>>   line-number-mode: t
>
>> Recent input:
>> ESC [ > 1 ; 2 3 0 5 ; 0 c C-x C-f . e m a c s RET C-v
>> C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v C-v ESC v ESC
>> v ESC v ESC v ESC v ESC v C-v C-v C-v C-v C-a C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-l C-v C-v C-v ESC v ESC v ESC v ESC v ESC v ESC v
>> ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC v ESC
>> v ESC v ESC v C-v C-l C-u C-u C-n C-n C-n DEL C-x SPC
>> SPC C-a C-x C-s C-v C-x C-s C-v C-v C-v C-v ESC v C-v
>> C-n C-n C-n C-n C-n C-n C-n C-n C-l C-u C-p C-p C-p
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n
>> C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-n C-l ESC
>> x r e p o r t - e m a c s - b u g RET
>
>> Recent messages:
>> ("emacs")
>> Loading /local/software/source-trees/emacs-jabber/jabber-autoloads.el (source)...done
>> call-interactively: Beginning of buffer [3 times]
>> Saving file /home/brown/.emacs...
>> Wrote /home/brown/.emacs
>> (No changes need to be saved)
>
>> Load-path shadows:
>> /local/software/source-trees/cc-mode/cc-fonts hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-fonts
>> /local/software/source-trees/cc-mode/cc-align hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-align
>> /local/software/source-trees/cc-mode/cc-menus hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-menus
>> /local/software/source-trees/cc-mode/cc-engine hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-engine
>> /local/software/source-trees/cc-mode/cc-mode hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-mode
>> /local/software/source-trees/cc-mode/cc-awk hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-awk
>> /local/software/source-trees/cc-mode/cc-defs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-defs
>> /local/software/source-trees/cc-mode/cc-vars hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-vars
>> /local/software/source-trees/cc-mode/cc-styles hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-styles
>> /local/software/source-trees/cc-mode/cc-bytecomp hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-bytecomp
>> /local/software/source-trees/cc-mode/cc-compat hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-compat
>> /local/software/source-trees/cc-mode/cc-cmds hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-cmds
>> /local/software/source-trees/cc-mode/cc-langs hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/progmodes/cc-langs
>> /local/software/package/org-5.13e/org-publish hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-publish
>> /local/software/package/org-5.13e/org hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org
>> /local/software/package/org-5.13e/org-install hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-install
>> /local/software/package/org-5.13e/org-mouse hides /local/software/package/emacs-23.3.1/share/emacs/23.3/lisp/org/org-mouse
>
>> Features:
>> (shadow sort mail-extr message ecomplete rfc822 mml easymenu mml-sec
>> password-cache mm-decode mm-bodies mm-encode mailcap mail-parse rfc2231
>> rfc2047 rfc2045 qp ietf-drums mailabbrev nnheader gnus-util netrc
>> time-date mm-util mail-prsvr gmm-utils wid-edit mailheader canlock sha1
>> hex-util hashcash mail-utils warnings emacsbug uniquify advice help-fns
>> advice-preload slime-autoloads regexp-opt cl cl-19 ediff-hook vc-hooks
>> lisp-float-type lisp-mode register page menu-bar rfn-eshadow timer
>> jit-lock font-lock syntax facemenu font-core frame cham georgian
>> utf-8-lang misc-lang vietnamese tibetan thai tai-viet lao korean
>> japanese hebrew greek romanian slovak czech european ethiopic indian
>> cyrillic chinese case-table epa-hook jka-cmpr-hook help simple abbrev
>> loaddefs button minibuffer faces cus-face files text-properties overlay
>> md5 base64 format env code-pages mule custom widget
>> hashtable-print-readable backquote make-network-process multi-tty emacs)
>
>

[-- Attachment #2: patch --]
[-- Type: application/octet-stream, Size: 4423 bytes --]

*** lisp-mode.el.~1~	2014-03-25 13:29:11.498131716 -0400
--- lisp-mode.el	2014-03-25 13:46:30.516011412 -0400
***************
*** 150,155 ****
--- 150,195 ----
  (defvar lisp-doc-string-elt-property 'doc-string-elt
    "The symbol property that holds the docstring position info.")
  
+ (defun lisp-string-in-doc-position-p (listbeg startpos)
+   (let* ((firstsym (and listbeg
+                         (save-excursion
+                           (goto-char listbeg)
+                           (and (looking-at "([ \t\n]*\\(\\(\\sw\\|\\s_\\)+\\)")
+                                (match-string 1)))))
+          (docelt (and firstsym
+                       (function-get (intern-soft firstsym)
+                                     lisp-doc-string-elt-property))))
+     (and docelt
+          ;; It's a string in a form that can have a docstring.
+          ;; Check whether it's in docstring position.
+          (save-excursion
+            (when (functionp docelt)
+              (goto-char (match-end 1))
+              (setq docelt (funcall docelt)))
+            (goto-char listbeg)
+            (forward-char 1)
+            (condition-case nil
+                (while (and (> docelt 0) (< (point) startpos)
+                            (progn (forward-sexp 1) t))
+                  (setq docelt (1- docelt)))
+              (error nil))
+            (and (zerop docelt) (<= (point) startpos)
+                 (progn (forward-comment (point-max)) t)
+                 (= (point) startpos))))))
+ 
+ (defun lisp-string-after-doc-keyword-p (listbeg startpos)
+   (and listbeg                          ; we are inside a Lisp form
+        (let* ((ok nil)
+               (prevsym (save-excursion
+                          (goto-char startpos)
+                          (condition-case nil
+                              (progn (backward-sexp 1) (setf ok t))
+                            (error nil))
+                          (and ok
+                               (looking-at "\\(\\sw+\\)")
+                               (match-string 1)))))
+          (equal prevsym ":documentation"))))
+ 
  (defun lisp-font-lock-syntactic-face-function (state)
    (if (nth 3 state)
        ;; This might be a (doc)string or a |...| symbol.
***************
*** 157,188 ****
          (if (eq (char-after startpos) ?|)
              ;; This is not a string, but a |...| symbol.
              nil
!           (let* ((listbeg (nth 1 state))
!                  (firstsym (and listbeg
!                                 (save-excursion
!                                   (goto-char listbeg)
!                                   (and (looking-at "([ \t\n]*\\(\\(\\sw\\|\\s_\\)+\\)")
!                                        (match-string 1)))))
!                  (docelt (and firstsym
!                               (function-get (intern-soft firstsym)
!                                             lisp-doc-string-elt-property))))
!             (if (and docelt
!                      ;; It's a string in a form that can have a docstring.
!                      ;; Check whether it's in docstring position.
!                      (save-excursion
!                        (when (functionp docelt)
!                          (goto-char (match-end 1))
!                          (setq docelt (funcall docelt)))
!                        (goto-char listbeg)
!                        (forward-char 1)
!                        (condition-case nil
!                            (while (and (> docelt 0) (< (point) startpos)
!                                        (progn (forward-sexp 1) t))
!                              (setq docelt (1- docelt)))
!                          (error nil))
!                        (and (zerop docelt) (<= (point) startpos)
!                             (progn (forward-comment (point-max)) t)
!                             (= (point) (nth 8 state)))))
                  font-lock-doc-face
                font-lock-string-face))))
      font-lock-comment-face))
--- 197,205 ----
          (if (eq (char-after startpos) ?|)
              ;; This is not a string, but a |...| symbol.
              nil
!           (let ((listbeg (nth 1 state)))
!             (if (or (lisp-string-in-doc-position-p listbeg startpos)
!                     (lisp-string-after-doc-keyword-p listbeg startpos))
                  font-lock-doc-face
                font-lock-string-face))))
      font-lock-comment-face))

bug#9130: 23.3; Lisp mode doc string enhancement

[Stefan Monnier]

> I have converted the change into a patch made with diff and
> have included it as an attachment.  The patch is relative to
> Emacs version 24.3.

Thank you, installed with a minor simplification.  Sorry for the delay.

> EIEIO supports defclass with :documentation strings, so I
> think the detection of such strings should be active in both
> emacs-lisp-mode and lisp-mode.

Yes, I think it's OK, indeed.


        Stefan

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

[-- Attachment #1: Type: text/plain, Size: 158 bytes --]

Eli,

Attached patch that updates etc/NEWS for fontification of strings
after :documentation in Lisp mode.

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

[-- Attachment #2: 0001-Document-Lisp-mode-fontification-for-strings-after-d.patch --]
[-- Type: text/x-patch, Size: 970 bytes --]

From 8621f7be8ec82eda08bbd1ddd6489651c5b5a067 Mon Sep 17 00:00:00 2001
From: Shakthi Kannan <author@shakthimaan.com>
Date: Wed, 16 Dec 2015 22:17:16 +0530
Subject: [PATCH] Document Lisp mode fontification for strings after
 :documentation

---
 etc/NEWS | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/etc/NEWS b/etc/NEWS
index 2788f5c..3980cbc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -631,7 +631,13 @@ respectively, `show-paren-when-point-inside-paren' or
 `show-paren-when-point-in-periphery'.
 
 ** Lisp mode
-*** Strings after `:documentation' are highlighted as docstrings.
+
++++
+*** Strings after `:documentation' are highlighted as docstrings. This
+enhances Lisp mode fontification to handle documentation of the form
+(:documentation "the doc string") used in Common Lisp code for CLOS
+class and slot documentation.
+
 
 ** Rectangle editing
 *** Rectangle Mark mode can have corners past EOL or in the middle of a TAB.
-- 
2.1.4

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Wed, 16 Dec 2015 22:40:30 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> 
> Attached patch that updates etc/NEWS for fontification of strings
> after :documentation in Lisp mode.

Thanks.  A couple of comments:

> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -631,7 +631,13 @@ respectively, `show-paren-when-point-inside-paren' or
>  `show-paren-when-point-in-periphery'.
>  
>  ** Lisp mode
> -*** Strings after `:documentation' are highlighted as docstrings.
> +
> ++++
> +*** Strings after `:documentation' are highlighted as docstrings. This
> +enhances Lisp mode fontification to handle documentation of the form
> +(:documentation "the doc string") used in Common Lisp code for CLOS
> +class and slot documentation.

The first sentence should be alone on its line, with the rest in the
following lines.

Also, you are marking this as documented, but in what manual did you
find this documented?  The original commit that added this feature
didn't include any documentation changes.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

Hi,

--- On Wed, Dec 16, 2015 at 11:23 PM, Eli Zaretskii <eliz@gnu.org> wrote:
| The first sentence should be alone on its line, with the rest in the
| following lines.
\--

Okay.

---
| Also, you are marking this as documented, but in what manual did you
| find this documented?  The original commit that added this feature
| didn't include any documentation changes.
\--

Since, the patch has made the documentation updated in NEWS file, I
marked it as '+++'. How else should I mark it?

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Wed, 16 Dec 2015 23:37:08 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> Cc: bug-gnu-emacs@gnu.org
> 
> ---
> | Also, you are marking this as documented, but in what manual did you
> | find this documented?  The original commit that added this feature
> | didn't include any documentation changes.
> \--
> 
> Since, the patch has made the documentation updated in NEWS file, I
> marked it as '+++'. How else should I mark it?

No, that's a misunderstanding.  The NEWS entries that are not marked
by either "+++" or "---" (and the corresponding code) need to be
considered as basis for updating one of the Emacs manuals.  The "+++"
mark means the corresponding manual has been updated.

IOW, the unmarked entries in NEWS are hints for updating the manuals
due to changes since the last release.  They should be expanded,
enriched with whatever you pick up from the doc strings and the code
itself, and described in the appropriate manual.

Sorry, I think that was clear.

Thanks.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

Hi,

--- On Thu, Dec 17, 2015 at 12:17 AM, Eli Zaretskii <eliz@gnu.org> wrote:
| IOW, the unmarked entries in NEWS are hints for updating the manuals
| due to changes since the last release.  They should be expanded,
| enriched with whatever you pick up from the doc strings and the code
| itself, and described in the appropriate manual.
\--

Okay. I shall update the manual along with the NEWS entry, and will
send a new patch.

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Thu, 17 Dec 2015 00:24:38 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> Cc: bug-gnu-emacs@gnu.org
> 
> Okay. I shall update the manual along with the NEWS entry, and will
> send a new patch.

Thank you.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

[-- Attachment #1: Type: text/plain, Size: 181 bytes --]

Hi,

Attached patch with updated manual, NEWS and docstrings:

* doc/emacs/display.texi
* etc/NEWS
* lisp/emacs-lisp/lisp-mode.el

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

[-- Attachment #2: 0001-Document-Lisp-mode-fontification-for-strings-after-d.patch --]
[-- Type: text/x-patch, Size: 2994 bytes --]

From fa87c4cf8a62d37b71e62f4b007d8a8cc43895cf Mon Sep 17 00:00:00 2001
From: Shakthi Kannan <author@shakthimaan.com>
Date: Thu, 17 Dec 2015 22:25:14 +0530
Subject: [PATCH] Document Lisp mode fontification for strings after
 documentation

---
 doc/emacs/display.texi       | 5 +++++
 etc/NEWS                     | 5 +++++
 lisp/emacs-lisp/lisp-mode.el | 3 +++
 3 files changed, 13 insertions(+)

diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
index a722ec4..73a5112 100644
--- a/doc/emacs/display.texi
+++ b/doc/emacs/display.texi
@@ -867,6 +867,11 @@ any string or comment.  Therefore, you should avoid placing an
 open-parenthesis or open-brace in the leftmost column, if it is inside
 a string or comment.  @xref{Left Margin Paren}, for details.
 
+@findex lisp-mode
+  Documentation of the form (:documentation ``the doc string'') now
+support fontification in Lisp mode. These forms are used in Common
+Lisp code for CLOS class and slot documentation.
+
 @findex font-lock-add-keywords
   Font Lock highlighting patterns already exist for most modes, but
 you may want to fontify additional patterns.  You can use the function
diff --git a/etc/NEWS b/etc/NEWS
index 2788f5c..2e0ea44 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -631,7 +631,12 @@ respectively, `show-paren-when-point-inside-paren' or
 `show-paren-when-point-in-periphery'.
 
 ** Lisp mode
+
++++
 *** Strings after `:documentation' are highlighted as docstrings.
+This enhances Lisp mode fontification to handle documentation of the
+form (:documentation "the doc string") used in Common Lisp code for
+CLOS class and slot documentation.
 
 ** Rectangle editing
 *** Rectangle Mark mode can have corners past EOL or in the middle of a TAB.
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 9ce0dfd..446afb5 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -486,6 +486,7 @@ This will generate compile-time constants from BINDINGS."
   "Default expressions to highlight in Lisp modes.")
 
 (defun lisp-string-in-doc-position-p (listbeg startpos)
+  "Returns true if Lisp string is in docstring position"
   (let* ((firstsym (and listbeg
                         (save-excursion
                           (goto-char listbeg)
@@ -516,6 +517,7 @@ This will generate compile-time constants from BINDINGS."
                 (= (point) startpos))))))
 
 (defun lisp-string-after-doc-keyword-p (listbeg startpos)
+  "Returns true if Lisp string contains :documentation"
   (and listbeg                          ; We are inside a Lisp form.
        (save-excursion
          (goto-char startpos)
@@ -524,6 +526,7 @@ This will generate compile-time constants from BINDINGS."
                   (looking-at ":documentation\\_>"))))))
 
 (defun lisp-font-lock-syntactic-face-function (state)
+  "Font lock a string after :documentation"
   (if (nth 3 state)
       ;; This might be a (doc)string or a |...| symbol.
       (let ((startpos (nth 8 state)))
-- 
2.1.4

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Thu, 17 Dec 2015 22:29:27 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> Cc: bug-gnu-emacs@gnu.org
> 
> Attached patch with updated manual, NEWS and docstrings:
> 
> * doc/emacs/display.texi
> * etc/NEWS
> * lisp/emacs-lisp/lisp-mode.el

Thanks.  Some comments below:

> diff --git a/doc/emacs/display.texi b/doc/emacs/display.texi
> index a722ec4..73a5112 100644
> --- a/doc/emacs/display.texi
> +++ b/doc/emacs/display.texi
> @@ -867,6 +867,11 @@ any string or comment.  Therefore, you should avoid placing an
>  open-parenthesis or open-brace in the leftmost column, if it is inside
>  a string or comment.  @xref{Left Margin Paren}, for details.
>  
> +@findex lisp-mode
> +  Documentation of the form (:documentation ``the doc string'') now
> +support fontification in Lisp mode. These forms are used in Common
> +Lisp code for CLOS class and slot documentation.

After looking at this node and at several other candidates, I
concluded that there's no place in any manual which should mention
this.  In particular, the node in which you made the change is about
user-level customizations of font-lock, whereas this new feature
cannot be customized on the user level.

In any case, please don't say "now" in the manual -- this is
appropriate for NEWS entries, which are read once when the user
upgrades, but not for a manual which will include the added text from
now on.

> diff --git a/etc/NEWS b/etc/NEWS
> index 2788f5c..2e0ea44 100644
> --- a/etc/NEWS
> +++ b/etc/NEWS
> @@ -631,7 +631,12 @@ respectively, `show-paren-when-point-inside-paren' or
>  `show-paren-when-point-in-periphery'.
>  
>  ** Lisp mode
> +
> ++++
>  *** Strings after `:documentation' are highlighted as docstrings.

Therefore, this should now be marked with "---", not "+++".

> diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
> index 9ce0dfd..446afb5 100644
> --- a/lisp/emacs-lisp/lisp-mode.el
> +++ b/lisp/emacs-lisp/lisp-mode.el
> @@ -486,6 +486,7 @@ This will generate compile-time constants from BINDINGS."
>    "Default expressions to highlight in Lisp modes.")
>  
>  (defun lisp-string-in-doc-position-p (listbeg startpos)
> +  "Returns true if Lisp string is in docstring position"

We use 'nil' and 'non-nil' for false and true.

Also, the doc string should explain the meaning of the function
arguments.  By contrast, you just say "string" and don't explain how
that string relates to LISTBEG and STARTPOS.

Finally, just say "string", there's no need to add "Lisp" -- this is
Lisp code, after all, so every string is a Lisp string.

Could you fix the patch along these lines and resubmit, please?

Thanks in advance.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

Hi,

--- On Fri, Dec 18, 2015 at 9:05 PM, Eli Zaretskii <eliz@gnu.org> wrote:
| Therefore, this should now be marked with "---", not "+++".
\--

Will change it.

---
| Also, the doc string should explain the meaning of the function
| arguments.
\--

I have asked the author of the patch for a meaningful doc string. Will
submit the patch as soon as I receive it.

Thanks for your feedback!

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Fri, 18 Dec 2015 21:28:31 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> Cc: bug-gnu-emacs@gnu.org
> 
> Thanks for your feedback!

Thanks for helping in this monumental task.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

[-- Attachment #1: Type: text/plain, Size: 175 bytes --]

Hi,

I have received the docstrings for the three functions from the
author, Robert Brown, and I am re-submitting the patch.

SK

--
Shakthi Kannan
http://www.shakthimaan.com

[-- Attachment #2: 0001-Document-Lisp-mode-fontification-for-strings-after-d.patch --]
[-- Type: text/x-patch, Size: 2436 bytes --]

From 28a9a0390ec8e05c732410f0b0678466a7280b16 Mon Sep 17 00:00:00 2001
From: Shakthi Kannan <author@shakthimaan.com>
Date: Wed, 30 Dec 2015 11:50:20 +0530
Subject: [PATCH] Document Lisp mode fontification for strings after
 documentation

---
 etc/NEWS                     | 5 +++++
 lisp/emacs-lisp/lisp-mode.el | 8 ++++++++
 2 files changed, 13 insertions(+)

diff --git a/etc/NEWS b/etc/NEWS
index 2788f5c..2f33cdb 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -631,7 +631,12 @@ respectively, `show-paren-when-point-inside-paren' or
 `show-paren-when-point-in-periphery'.
 
 ** Lisp mode
+
+---
 *** Strings after `:documentation' are highlighted as docstrings.
+This enhances Lisp mode fontification to handle documentation of the
+form (:documentation "the doc string") used in Common Lisp code for
+CLOS class and slot documentation.
 
 ** Rectangle editing
 *** Rectangle Mark mode can have corners past EOL or in the middle of a TAB.
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 9ce0dfd..231b33f 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -486,6 +486,9 @@ lisp-cl-font-lock-keywords
   "Default expressions to highlight in Lisp modes.")
 
 (defun lisp-string-in-doc-position-p (listbeg startpos)
+   "Return true if STARTPOS is a position inside a list where a
+docstring may occur.  LISTBEG is the position of the start of the
+innermost list containing STARTPOS."
   (let* ((firstsym (and listbeg
                         (save-excursion
                           (goto-char listbeg)
@@ -516,6 +519,9 @@ lisp-string-in-doc-position-p
                 (= (point) startpos))))))
 
 (defun lisp-string-after-doc-keyword-p (listbeg startpos)
+  "Return true if STARTPOS is a position inside a list right
+after a :documentation symbol.  LISTBEG is the position of the
+start of the innermost list containing STARTPOS."
   (and listbeg                          ; We are inside a Lisp form.
        (save-excursion
          (goto-char startpos)
@@ -524,6 +530,8 @@ lisp-string-after-doc-keyword-p
                   (looking-at ":documentation\\_>"))))))
 
 (defun lisp-font-lock-syntactic-face-function (state)
+  "Return the Lisp font lock syntactic face function for the
+position represented by STATE, a `parse-partial-sexp' state."
   (if (nth 3 state)
       ;; This might be a (doc)string or a |...| symbol.
       (let ((startpos (nth 8 state)))
-- 
2.1.4

bug#9130: Document Lisp mode fontification for strings after :documentation

[Eli Zaretskii]

> Date: Wed, 30 Dec 2015 11:52:38 +0530
> From: Shakthi Kannan <shakthimaan@gmail.com>
> Cc: bug-gnu-emacs@gnu.org
> 
> I have received the docstrings for the three functions from the
> author, Robert Brown, and I am re-submitting the patch.

Thanks, pushed with some changes.  Please see how I changed the doc
strings for conformance with Emacs coding style: the first line of the
doc string must be a full sentence.  If the first sentence is too long
for that, make it shorter, omitting some details for the rest of the
doc string.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Xue Fuqiao]

On Thu, Dec 31, 2015 at 2:02 AM, Eli Zaretskii <eliz@gnu.org> wrote:
>> Date: Wed, 30 Dec 2015 11:52:38 +0530
>> From: Shakthi Kannan <shakthimaan@gmail.com>
>> Cc: bug-gnu-emacs@gnu.org
>>
>> I have received the docstrings for the three functions from the
>> author, Robert Brown, and I am re-submitting the patch.
>
> Thanks, pushed with some changes.  Please see how I changed the doc
> strings for conformance with Emacs coding style: the first line of the
> doc string must be a full sentence.  If the first sentence is too long
> for that, make it shorter, omitting some details for the rest of the
> doc string.

Shakthi, please see (info "(elisp) Documentation Tips") for some tips
and conventions for writing/formatting doc strings.

bug#9130: Document Lisp mode fontification for strings after :documentation

[Shakthi Kannan]

Hi,

--- On Thu, Dec 31, 2015 at 5:39 AM, Xue Fuqiao <xfq.free@gmail.com> wrote:
| Shakthi, please see (info "(elisp) Documentation Tips") for some tips
| and conventions for writing/formatting doc strings.
\--

Thanks for correcting my mistakes. I shall go through the
documentation and check them before submitting the next patch.

With regards,

SK

-- 
Shakthi Kannan
http://www.shakthimaan.com