From e832febfb4089418e0152c805e24dee977a7590d Mon Sep 17 00:00:00 2001
From: Noam Postavsky <npostavs@gmail.com>
Date: Wed, 14 Jun 2017 00:08:15 -0400
Subject: [PATCH] Allow comment-indent-functions to specify exact indentation
 (Bug#385)

* lisp/newcomment.el (comment-choose-indent): Interpret a cons of two
integers as indicating a range of acceptable indentation.
(comment-indent): Don't apply `comment-inline-offset',
`comment-choose-indent' already does that.
(comment-indent-function):
* doc/emacs/programs.texi (Options for Comments): Document new
acceptable return values.
* etc/NEWS: Announce it.
---
 doc/emacs/programs.texi |  9 ++++++---
 etc/NEWS                |  4 ++++
 lisp/newcomment.el      | 35 ++++++++++++++++++-----------------
 3 files changed, 28 insertions(+), 20 deletions(-)

diff --git a/doc/emacs/programs.texi b/doc/emacs/programs.texi
index 222d1c2a4de..27ac0eb6400 100644
--- a/doc/emacs/programs.texi
+++ b/doc/emacs/programs.texi
@@ -1146,9 +1146,12 @@ comment or for aligning an existing comment.  It is set differently by
 various major modes.  The function is called with no arguments, but with
 point at the beginning of the comment, or at the end of a line if a new
 comment is to be inserted.  It should return the column in which the
-comment ought to start.  For example, in Lisp mode, the indent hook
-function bases its decision on how many semicolons begin an existing
-comment, and on the code in the preceding lines.
+comment ought to start.  For example, the default hook function bases
+its decision on how many comment characters begin an existing comment.
+
+Emacs also tries to align comments on adjacent lines.  To override
+this, the function may return a cons of two (possibly equal) integers
+to indicate an acceptable range of indentation.
 
 @node Documentation
 @section Documentation Lookup
diff --git a/etc/NEWS b/etc/NEWS
index 83cb73f4a98..13805ce0da7 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -405,6 +405,10 @@ display of raw bytes from octal to hex.
 ** You can now provide explicit field numbers in format specifiers.
 For example, '(format "%2$s %1$s" "X" "Y")' produces "Y X".
 
++++
+** 'comment-indent-function' values may now return a cons to specify a
+range of indentation.
+
 
 * Editing Changes in Emacs 26.1
 
diff --git a/lisp/newcomment.el b/lisp/newcomment.el
index 118549f421c..8772b52376d 100644
--- a/lisp/newcomment.el
+++ b/lisp/newcomment.el
@@ -142,9 +142,10 @@ Should be an empty string if comments are terminated by end-of-line.")
 ;;;###autoload
 (defvar comment-indent-function 'comment-indent-default
   "Function to compute desired indentation for a comment.
-This function is called with no args with point at the beginning of
-the comment's starting delimiter and should return either the desired
-column indentation or nil.
+This function is called with no args with point at the beginning
+of the comment's starting delimiter and should return either the
+desired column indentation, a range of acceptable
+indentation (MIN . MAX), or nil.
 If nil is returned, indentation is delegated to `indent-according-to-mode'.")
 
 ;;;###autoload
@@ -649,13 +650,20 @@ The criteria are (in this order):
 - prefer INDENT (or `comment-column' if nil).
 Point is expected to be at the start of the comment."
   (unless indent (setq indent comment-column))
-  ;; Avoid moving comments past the fill-column.
-  (let ((max (+ (current-column)
-                (- (or comment-fill-column fill-column)
-                   (save-excursion (end-of-line) (current-column)))))
-        (other nil)
-        (min (save-excursion (skip-chars-backward " \t")
-                             (if (bolp) 0 (+ comment-inline-offset (current-column))))))
+  (let ((other nil)
+        min max)
+    (pcase indent
+      (`(,lo . ,hi) (setq min lo) (setq max hi)
+       (setq indent comment-column))
+      (_ ;; Avoid moving comments past the fill-column.
+       (setq max (+ (current-column)
+                    (- (or comment-fill-column fill-column)
+                       (save-excursion (end-of-line) (current-column)))))
+       (setq min (save-excursion
+                   (skip-chars-backward " \t")
+                   ;; Leave at least `comment-inline-offset' space after
+                   ;; other nonwhite text on the line.
+                   (if (bolp) 0 (+ comment-inline-offset (current-column)))))))
     ;; Fix up the range.
     (if (< max min) (setq max min))
     ;; Don't move past the fill column.
@@ -750,13 +758,6 @@ If CONTINUE is non-nil, use the `comment-continue' markers if any."
 	  ;; If the comment is at the right of code, adjust the indentation.
 	  (unless (save-excursion (skip-chars-backward " \t") (bolp))
 	    (setq indent (comment-choose-indent indent)))
-	  ;; Update INDENT to leave at least one space
-	  ;; after other nonwhite text on the line.
-	  (save-excursion
-	    (skip-chars-backward " \t")
-	    (unless (bolp)
-	      (setq indent (max indent
-                                (+ (current-column) comment-inline-offset)))))
 	  ;; If that's different from comment's current position, change it.
 	  (unless (= (current-column) indent)
 	    (delete-region (point) (progn (skip-chars-backward " \t") (point)))
-- 
2.39.2