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

[Eli Zaretskii <eliz@gnu.org>]

> 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.