bug#33516: Should the docstring for flymake-diag-region mention behavior with narrowing?

bug#33516: Should the docstring for flymake-diag-region mention behavior with narrowing?

[Matthew Bregg]

[-- Attachment #1.1: Type: text/plain, Size: 183 bytes --]

Currently it can be confusing when developing a flymake checker that
flymake-diag-region does not handle narrowing.

Updating the comment to mention this seems useful to me.

Thanks!

[-- Attachment #1.2: Type: text/html, Size: 252 bytes --]

[-- Attachment #2: 0001-Update-documentation-for-flymake.patch --]
[-- Type: text/x-patch, Size: 1119 bytes --]

From 0b4712c8553b918227bd58a2071a0dbdecaa04c0 Mon Sep 17 00:00:00 2001
From: Matthew Bregg <bregg@google.com>
Date: Fri, 16 Nov 2018 15:01:14 -0500
Subject: [PATCH] Update documentation for flymake.

Flymake flymake-diag-region does not mention behavior with narrowing, which can be confusing.
---
 lisp/progmodes/flymake.el | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/lisp/progmodes/flymake.el b/lisp/progmodes/flymake.el
index f0f93f1087..58bbbd500e 100644
--- a/lisp/progmodes/flymake.el
+++ b/lisp/progmodes/flymake.el
@@ -384,7 +384,9 @@ verify FILTER, a function, and sort them by COMPARE (using KEY)."
 (defun flymake-diag-region (buffer line &optional col)
   "Compute BUFFER's region (BEG . END) corresponding to LINE and COL.
 If COL is nil, return a region just for LINE.  Return nil if the
-region is invalid."
+region is invalid.
+If the BUFFER has been narrowed,
+the region returned will correspond to the BUFFER's narrowed state."
   (condition-case-unless-debug _err
       (with-current-buffer buffer
         (let ((line (min (max line 1)
-- 
2.19.1.1215.g8438c0b245-goog

bug#33516: Should the docstring for flymake-diag-region mention behavior with narrowing?

[Lars Ingebrigtsen]

Matthew Bregg <bregg@google.com> writes:

> Currently it can be confusing when developing a flymake checker that
> flymake-diag-region does not handle narrowing.
>
> Updating the comment to mention this seems useful to me.

[...]

> -region is invalid."
> +region is invalid.
> +If the BUFFER has been narrowed,
> +the region returned will correspond to the BUFFER's narrowed state."

Hm...  I think we generally assume that all functions (except explicitly
documented not to) work on the narrowed section of a buffer?  So
documenting this in this specific function doesn't seem natural do me,
and I'm closing this bug report.  If somebody disagrees, please reopen.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no