From 86312ffd93e54bc8993740479c9de3df69935185 Mon Sep 17 00:00:00 2001
From: Shakthi Kannan <shakthimaan@gmail.com>
Date: Wed, 30 Dec 2015 19:59:12 +0200
Subject: [PATCH] Document support for ':documentation' in Lisp mode

* lisp/emacs-lisp/lisp-mode.el (lisp-string-in-doc-position-p)
(lisp-string-after-doc-keyword-p)
(lisp-font-lock-syntactic-face-function): Add doc strings.
---
 etc/NEWS                     | 5 +++++
 lisp/emacs-lisp/lisp-mode.el | 9 +++++++++
 2 files changed, 14 insertions(+)

diff --git a/etc/NEWS b/etc/NEWS
index 80e999956c7..9f321667945 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -638,7 +638,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
 
diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el
index 3448b72c3f1..e99f8a55ab1 100644
--- a/lisp/emacs-lisp/lisp-mode.el
+++ b/lisp/emacs-lisp/lisp-mode.el
@@ -488,6 +488,9 @@ This will generate compile-time constants from BINDINGS."
   "Default expressions to highlight in Lisp modes.")
 
 (defun lisp-string-in-doc-position-p (listbeg startpos)
+   "Return true if a doc string may occur at STARTPOS inside a list.
+LISTBEG is the position of the start of the innermost list
+containing STARTPOS."
   (let* ((firstsym (and listbeg
                         (save-excursion
                           (goto-char listbeg)
@@ -518,6 +521,9 @@ This will generate compile-time constants from BINDINGS."
                 (= (point) startpos))))))
 
 (defun lisp-string-after-doc-keyword-p (listbeg startpos)
+  "Return true if `:documentation' symbol ends at STARTPOS inside a list.
+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)
@@ -526,6 +532,9 @@ This will generate compile-time constants from BINDINGS."
                   (looking-at ":documentation\\_>"))))))
 
 (defun lisp-font-lock-syntactic-face-function (state)
+  "Return syntactic face function for the position represented by STATE.
+STATE is a `parse-partial-sexp' state, and the returned function is the
+Lisp font lock syntactic face function."
   (if (nth 3 state)
       ;; This might be a (doc)string or a |...| symbol.
       (let ((startpos (nth 8 state)))
-- 
2.39.5