Fix Pike Mode's autodoc doc comments style's continued lines.

* lisp/progmodes/cc-engine.el (c-forward-sws, c-backward-sws): Recognize
matches of c-doc-line-join-re as syntactic whitespace.
(c-find-decl-prefix-search): Recognize and move over matches of
c-doc-line-join-re as whitespace.
(c-find-decl-spots): Before moving backward a char, check (bobp).  Before
moving forward over a comment, check it isn't possibly a "bright" comment.

* lisp/progmodes/cc-fonts.el (c-get-doc-comment-style): New function,
extracted from c-compose-keywords-list.
(c-compose-keywords-list): Call the above new function.
(pike-font-lock-keywords, pike-font-lock-keywords-2)
(pike-font-lock-keywords-3): Call c-set-doc-comment-res.
(c-doc-line-join-re, c-doc-bright-comment-start-re, c-doc-line-join-end-ch):
New variables.
(c-set-doc-comment-re-element, c-set-doc-comment-char-list): New macros.
(c-set-doc-comment-res): New function.
(c-font-lock-doc-comments): For consistency and repeatability, in a sequence
of C++ style doc comments, don't fontify the region between BOL and the
comment marker.
(autodoc-line-join-re, autodoc-bright-comment-start-re)
(autodoc-line-join-end-ch): New variables.

* lisp/progmodes/cc-mode.el (c-doc-fl-decl-start, c-doc-fl-decl-end): New
functions.
(c-change-expand-fl-region, c-context-expand-fl-region): Call the above two
new functions for extra possibilities for the start and end of a construct.

* doc/misc/cc-mode.texi (Doc Comments): Add a sentence drawing attention to
the possibility of fontifying constructs within a doc comment.

1 files changed, 94 insertions, 7 deletions

diff --git a/lisp/progmodes/cc-fonts.el b/lisp/progmodes/cc-fonts.el
index e7a3748af43..5832f1f451c 100644
--- a/lisp/progmodes/cc-fonts.el
+++ b/lisp/progmodes/cc-fonts.el
@@ -2089,6 +2089,14 @@ higher."
 	    (c-lang-const c-complex-decl-matchers)
 	    (c-lang-const c-basic-matchers-after)))
 
+(defun c-get-doc-comment-style ()
+  ;; Get the symbol (or list of symbols) constituting the document style.
+  ;; Return nil if there is no such, otherwise something like `autodoc'.
+  (if (consp (car-safe c-doc-comment-style))
+      (cdr-safe (or (assq c-buffer-is-cc-mode c-doc-comment-style)
+		    (assq 'other c-doc-comment-style)))
+    c-doc-comment-style))
+
 (defun c-compose-keywords-list (base-list)
   ;; Incorporate the font lock keyword lists according to
   ;; `c-doc-comment-style' on the given keyword list and return it.
@@ -2099,11 +2107,7 @@ higher."
   (unless (memq c-doc-face-name c-literal-faces)
     (setq c-literal-faces (cons c-doc-face-name c-literal-faces)))
 
-  (let* ((doc-keywords
-	  (if (consp (car-safe c-doc-comment-style))
-	      (cdr-safe (or (assq c-buffer-is-cc-mode c-doc-comment-style)
-			    (assq 'other c-doc-comment-style)))
-	    c-doc-comment-style))
+  (let* ((doc-keywords (c-get-doc-comment-style))
 	 (list (nconc (c--mapcan
 		       (lambda (doc-style)
 			 (let ((sym (intern
@@ -2552,15 +2556,88 @@ need for `pike-font-lock-extra-types'.")
   "Default expressions to highlight in Pike mode.")
 
 (defun pike-font-lock-keywords-2 ()
+  (c-set-doc-comment-res)
   (c-compose-keywords-list pike-font-lock-keywords-2))
 (defun pike-font-lock-keywords-3 ()
+  (c-set-doc-comment-res)
   (c-compose-keywords-list pike-font-lock-keywords-3))
 (defun pike-font-lock-keywords ()
+  (c-set-doc-comment-res)
   (c-compose-keywords-list pike-font-lock-keywords))
 
 
 ;;; Doc comments.
 
+(defvar c-doc-line-join-re "a\\`")
+;; Matches a join of two lines in a doc comment.
+;; This should not be changed directly, but instead set by
+;; `c-setup-doc-comment-style'.  This variable is used in `c-find-decl-spots'
+;; in (e.g.) autodoc style comments to bridge the gap between a "@\n" at an
+;; EOL and the token following "//!" on the next line.
+
+(defvar c-doc-bright-comment-start-re "a\\`")
+;; Matches the start of a "bright" comment, one whose contents may be
+;; fontified by, e.g., `c-font-lock-declarations'.
+
+(defvar c-doc-line-join-end-ch nil)
+;; A list of characters, each being a last character of a doc comment marker,
+;; e.g. the ! from pike autodoc's "//!".
+
+(defmacro c-set-doc-comment-re-element (suffix)
+  ;; Set the variable `c-doc-line-join-re' to a buffer local value suitable
+  ;; for the current doc comment style, or kill the local value.
+  (let ((var (intern (concat "c-doc" suffix))))
+    `(let* ((styles (c-get-doc-comment-style))
+	    elts)
+       (when (atom styles)
+	 (setq styles (list styles)))
+       (setq elts
+	     (mapcar (lambda (style)
+		       (let ((sym
+			      (intern-soft
+			       (concat (symbol-name style) ,suffix))))
+			 (and sym
+			      (boundp sym)
+			      (symbol-value sym))))
+		     styles))
+       (setq elts (delq nil elts))
+       (setq elts (and elts
+		       (concat "\\("
+			       (mapconcat #'identity elts "\\|")
+			       "\\)")))
+       (if elts
+	   (set (make-local-variable ',var) elts)
+	 (kill-local-variable ',var)))))
+
+(defmacro c-set-doc-comment-char-list (suffix)
+  ;; Set the variable 'c-doc-<suffix>' to the list of *-<suffix>, which must
+  ;; be characters, and * represents the doc comment style.
+  (let ((var (intern (concat "c-doc" suffix))))
+    `(let* ((styles (c-get-doc-comment-style))
+	    elts)
+       (when (atom styles)
+	 (setq styles (list styles)))
+       (setq elts
+	     (mapcar (lambda (style)
+		       (let ((sym
+			      (intern-soft
+			       (concat (symbol-name style) ,suffix))))
+			 (and sym
+			      (boundp sym)
+			      (symbol-value sym))))
+		     styles))
+       (setq elts (delq nil elts))
+       (if elts
+	   (set (make-local-variable ',var) elts)
+	 (kill-local-variable ',var)))))
+
+(defun c-set-doc-comment-res ()
+  ;; Set the variables `c-doc-line-join-re' and
+  ;; `c-doc-bright-comment-start-re' from the current doc comment style(s).
+  (c-set-doc-comment-re-element "-line-join-re")
+  (c-set-doc-comment-re-element "-bright-comment-start-re")
+  (c-set-doc-comment-char-list "-line-join-end-ch"))
+
 (defun c-font-lock-doc-comments (prefix limit keywords)
   ;; Fontify the comments between the point and LIMIT whose start
   ;; matches PREFIX with `c-doc-face-name'.  Assumes comments have been
@@ -2621,17 +2698,20 @@ need for `pike-font-lock-extra-types'.")
 	    (goto-char comment-beg)
 	    (while (and (progn
 			  (c-forward-single-comment)
+			  (c-put-font-lock-face comment-beg (point)
+						c-doc-face-name)
 			  (skip-syntax-forward " ")
+			  (setq comment-beg (point))
 			  (< (point) limit))
 			(looking-at prefix))))
 	(goto-char comment-beg)
-	(c-forward-single-comment))
+	(c-forward-single-comment)
+	(c-put-font-lock-face comment-beg (point) c-doc-face-name))
       (if (> (point) limit) (goto-char limit))
       (setq comment-beg nil)
 
       (let ((region-end (point))
 	    (keylist keywords) keyword matcher highlights)
-	(c-put-font-lock-face region-beg region-end c-doc-face-name)
 	(save-restriction
 	  ;; Narrow to the doc comment.  Among other things, this
 	  ;; helps by making "^" match at the start of the comment.
@@ -2838,6 +2918,13 @@ need for `pike-font-lock-extra-types'.")
      0 'font-lock-warning-face prepend nil)
     ))
 
+(defconst autodoc-line-join-re "@[\n\r][ \t]*/[/*]!")
+;; Matches a line continuation in autodoc comment style.
+(defconst autodoc-bright-comment-start-re "/[/*]!")
+;; Matches an autodoc comment opener.
+(defconst autodoc-line-join-end-ch ?!)
+;; The final character of `autodoc-line-join-re'.
+
 (defun autodoc-font-lock-keywords ()
   ;; Note that we depend on that `c-current-comment-prefix' has got
   ;; its proper value here.