bug#18478: 24.4.50; doc string of `clone-indirect-buffer'

bug#18478: 24.4.50; doc string of `clone-indirect-buffer'

[Drew Adams]

.. should say that it returns the indirect buffer created.

In GNU Emacs 24.4.50.1 (i686-pc-mingw32)
 of 2014-08-15 on LEG570
Bzr revision: 117706 rgm@gnu.org-20140815043406-p5hbu97cbm7pulcn
Windowing system distributor `Microsoft Corp.', version 6.1.7601
Configured using:
 `configure --enable-checking 'CFLAGS=-O0 -g3' CPPFLAGS=-DGLYPH_DEBUG=1'

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Tom Willemse]

[-- Attachment #1: Type: text/plain, Size: 177 bytes --]

Hey,

I hope it's ok that I'm replying to this bug.

I've attached a suggestion for mentioning the return value for
`clone-indirect-buffer'. Please let me know what you think.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch mentioning the return value --]
[-- Type: text/x-diff, Size: 2756 bytes --]

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: tom@ryuslash.org-20140917220512-i61eqo2e0ir8dhdl
# target_branch: bzr://bzr.sv.gnu.org/emacs/trunk/
# testament_sha1: 14f39b93edb4937309c738111fb8220fc3776acd
# timestamp: 2014-09-18 00:10:58 +0200
# base_revision_id: eggert@cs.ucla.edu-20140917195831-xarn36t9318izhtl
# 
# Begin patch
=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2014-09-17 09:17:27 +0000
+++ lisp/ChangeLog	2014-09-17 22:05:12 +0000
@@ -1,3 +1,7 @@
+2014-09-17  Tom Willemse  <tom@ryuslash.org>
+
+	* simple.el (clone-indirect-buffer): Mention the return value.
+
 2014-09-17  Reuben Thomas  <rrt@sc3d.org>
 
 	* progmodes/js.el: Add interpreter-mode-alist support for various

=== modified file 'lisp/simple.el'
--- lisp/simple.el	2014-08-28 01:59:29 +0000
+++ lisp/simple.el	2014-09-17 22:05:12 +0000
@@ -7577,7 +7577,9 @@
 This is always done when called interactively.
 
 Optional third arg NORECORD non-nil means do not put this buffer at the
-front of the list of recently selected ones."
+front of the list of recently selected ones.
+
+This function returns the newly created indirect buffer."
   (interactive
    (progn
      (if (get major-mode 'no-clone-indirect)

# Begin bundle
IyBCYXphYXIgcmV2aXNpb24gYnVuZGxlIHY0CiMKQlpoOTFBWSZTWRFVfucAAiffgAAwUHP/91oG
BIC////wUAR28NGmxzklac2hJSmmFPFNN6AnpTxI8KNPUaA0DBlBMAEU/SE0bUAAaAABIkCmE0Ta
Kek21Q00aNDTQHqZMMNDQAAAaAAAAAEkUyNAmCMRNMJPU8ojIabINEDW8RUos8613hLcssjmq15g
GkWwhmzUh0Ut7GUCrDrL2mP8d6/s67G4zZSThHHHQj8l3/ofqOfgT2jqS5wP+iYTKXUcI0xDy4X4
+X21cg5Hf3CZhG5ccT014fgqtPYrHIJgGDeW3gYzalPqwt/JQ0bDdV91BFvGsRJZmBdbIy1toFey
0cwm7YJTMJRJlI9SAuLAZ2EfnYJwUPiVzKpM6hAIzEsqQLVdc6dc+MrjV0KcDeYODMSBiJWS5tN5
SChrEoIO0ClxpKRro2GyiDsC600ee1YixTM+BcYGzLQCUKCJe8kF4qu7oUBagTxQPwIPVWUnA/Us
CNU+0xdErrD5gZkDWNNb4FJBVqu6DMLytCsu5Kcnsvm+RBnyMVrsVMhiDqsLdbShuNNsCxljqusP
2K3VqM6qVyiBNfaV5Wvt84KKtKafGwgfkXPyFfrIoKTmByVWht0FKwpJjIfNPGUNsxsIOqLHApaW
fBOVkTWqwziDsJ43vk5zNewLlfNRwd92cILSIsoutoCZpYAQsnhPZExTNXCgq4whXnauOI5l4ZuM
jHeZ/Yz6OjK69vZCOGt1xhTgHW6kmrkW1M7F6jd03sfFQ+sfz5eBFl3pDsXjG3+7SMCb7GSqPBo+
ndMOSgX+0pYXdctDjn5bN/ZijLmTk+uZYukSoVIhxsZnWd5mUM7nMxHaF1QrxSDscMlIcZ7bssLX
oF8kzeSjCNiswvejwq6A1DvIOxCKIRLmHA6KK9AJ7V/TC2HUiE5kTJcjQB/ja/M4HbodzsVXNUzz
0jI2d0PVQnFQic6MWETHWlqrjRBHCxn1qHNHzav0bmngaBtVdVEkivbfuJAHvCJGveVqvQ3jeD94
uGMBQPWGakJlivgvY6nc6ZuYwZ8loCuvoZDG9XKPflxEcncX4czA4hd+uixRA5gW2l03uho1LeL3
Ji5FXJDISX0sa9EokWASrSpHis4DVosX857ClE0puTEwwwVorcJ1MI9DwhjAYi9FB9TTrukdqSwl
U54dp8WI61Q5YHrpOamjAc1UY01kV10AmEHgsrBUTyQTsFbrd7ASFRUe952MBGNQEDtRJTo/wFYt
ZlfvM/zTowwTKLIo0h6+BaAb2E2IA8j1vJZwJSX8SS0AqdooyDSjHLCrnG6Hgd4InZdTG7F8AtGw
IQdtQsae6KELEgOW4IWJIRAGNa7YH/FPMJHSFcYpaW0NGE+F2Ba8+SeZmmU7jJEQkwfbHFdjcmCL
81icl5le5cxGZ4FUv7tR0/18BZCj3LxhGze2SYjTeKnoLuSKcKEgIqr9zg==

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Drew Adams]

> I've attached a suggestion for mentioning the return value for
> `clone-indirect-buffer'. Please let me know what you think.

Looks OK to me.  You can also simplify it to just "Returns...".

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Tom Willemse]

Hey Drew,

Drew Adams <drew.adams@oracle.com> writes:

>> I've attached a suggestion for mentioning the return value for
>> `clone-indirect-buffer'. Please let me know what you think.
>
> Looks OK to me.  You can also simplify it to just "Returns...".

Certainly, if that has your preference. I just thought that because it
is a new paragraph and the ones before it talk about the meanings of the
arguments it would be clearer to explicitly state it's about the
function.

I actually would have liked to start the docstring off with "Create and
return ..." as the docstring for `clone-buffer' does, but checkdoc then
started complaining about the line being more than 80 characters long.

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Drew Adams]

> >> I've attached a suggestion for mentioning the return value for
> >> `clone-indirect-buffer'. Please let me know what you think.
> >
> > Looks OK to me.  You can also simplify it to just "Returns...".
> 
> Certainly, if that has your preference.

I have no preference.  And my preference doesn't count for anything.
I just reported the bug.

> I just thought that because it is a new paragraph and the ones
>  before it talk about the meanings of the arguments it would be
> clearer to explicitly state it's about the function.

Yes, but I don't see any chance for confusion there.  It is only
the function return value that matters. And arguments do not
"return".  They are evaluated, of course, and their values are
returned by that evaluation.  But we just speak of their "values".

> I actually would have liked to start the docstring off with "Create
> and return ..." as the docstring for `clone-buffer' does, but checkdoc
> then started complaining about the line being more than 80 characters
> long.

FWIW, I don't put a lot of stock in checkdoc, personally. ;-)

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Stefan Monnier]

>> I actually would have liked to start the docstring off with "Create
>> and return ..." as the docstring for `clone-buffer' does, but checkdoc
>> then started complaining about the line being more than 80 characters
>> long.

> FWIW, I don't put a lot of stock in checkdoc, personally. ;-)

Its recommendations shouldn't be heeded blindly, indeed, but the
80-columns limit is something that should really be obeyed
whenever possible.


        Stefan


PS: Thanks Tom.  Your patch looks good, as does the one for
prog-mode-hook.  Hopefully someone else will get to install them before
I do.

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Drew Adams]

> > FWIW, I don't put a lot of stock in checkdoc, personally. ;-)
> 
> Its recommendations shouldn't be heeded blindly, indeed, but the
> 80-columns limit is something that should really be obeyed
> whenever possible.

Agreed wrt respecting doc-string line-length conventions.

But 80 chars is the absolute limit.  Doc strings should really be 
quite a bit shorter than that.  `emacs-lisp-docstring-fill-column'
defaults to 65, for example.

The actual convention is this (from (elisp) `Documentation Tips'):

 Format the documentation string so that it fits in an Emacs window
 on an 80-column screen.  It is a good idea for most lines to be no
 wider than 60 characters.  The first line should not be wider than
            ^^^^^^^^^^^^^
 67 characters or it will look bad in the output of `apropos'.

 You can fill the text if that looks good.  Emacs Lisp mode fills
 documentation strings to the width specified by
 `emacs-lisp-docstring-fill-column'.  However, you can sometimes
 make a documentation string much more readable by adjusting its
 line breaks with care.  Use blank lines between sections if the
 documentation string is long.

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Tom Willemse]

[-- Attachment #1: Type: text/plain, Size: 173 bytes --]

Hey Drew, Stefan,

Thanks for both your responses. I've attached the same patch with the
simplification suggested by Drew. Whomever applies one can pick which
they prefer.


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: Patch --]
[-- Type: text/x-diff, Size: 2713 bytes --]

# Bazaar merge directive format 2 (Bazaar 0.90)
# revision_id: tom@ryuslash.org-20140920232659-ssj464v1st1f79od
# target_branch: bzr://bzr.sv.gnu.org/emacs/trunk/
# testament_sha1: fffb97df6a9ff5f3ca2f27f89d88d4797e7ab334
# timestamp: 2014-09-21 01:27:28 +0200
# base_revision_id: dgutov@yandex.ru-20140919173311-0sqv853yxogkno1j
# 
# Begin patch
=== modified file 'lisp/ChangeLog'
--- lisp/ChangeLog	2014-09-19 17:33:11 +0000
+++ lisp/ChangeLog	2014-09-20 23:26:59 +0000
@@ -1,3 +1,7 @@
+2014-09-20  Tom Willemse  <tom@ryuslash.org>
+
+	* simple.el (clone-indirect-buffer): Mention the return value.
+
 2014-09-19  Dmitry Gutov  <dgutov@yandex.ru>
 
 	* emacs-lisp/lisp.el (lisp-completion-at-point): Only calculate

=== modified file 'lisp/simple.el'
--- lisp/simple.el	2014-08-28 01:59:29 +0000
+++ lisp/simple.el	2014-09-20 23:26:59 +0000
@@ -7577,7 +7577,9 @@
 This is always done when called interactively.
 
 Optional third arg NORECORD non-nil means do not put this buffer at the
-front of the list of recently selected ones."
+front of the list of recently selected ones.
+
+Returns the newly created indirect buffer."
   (interactive
    (progn
      (if (get major-mode 'no-clone-indirect)

# Begin bundle
IyBCYXphYXIgcmV2aXNpb24gYnVuZGxlIHY0CiMKQlpoOTFBWSZTWed9NqYAAi1fgAAwUHP/91oG
FIC////wUAR5XgTm1yhAEEkk0qfo1T9GEYBNMKj9SepmoPUNNAJVGKaaeU9TZT1GmgGgAAAAEoIT
SNHkkZpB6gABo0GgBgNAAANAAAAAAEkhMU2QBIT9TCh6mTaUZBp6noyKYWl7ukttey9ZvW3RoTTq
vjnQRYznqjYshW7Y+ZOp3EFRRduxN0Jbyq16kXVkMMuI3qW/sT2bWPQWI+6B9oRy93UcD/WgMJ7G
u8WOOcpXLsEDCKVjyM7Lt4fRjQ+So0AUDIwcJpWpPconEoD61rvwdC2wQ9g0N5Wkjst7ZCoywdo/
rYk+bhJxGA8DeVHCeWHT0I9aicAWKZGD8ohVXso2Bz2oczYr0tDQWFKCjJ32uxfq5oDxMPErgvxO
O74lKKa1MA7D5UkS4WZitmGb9MzI15AeQfoCOZWj96VfJyFACAvWQGw9+mBjjYBP21L5QNXIwOWG
2M9zoEigbrh4uNoFA2gOtnaTxmV8wptULSt4wgtEri5jnEzfgC4E6PIK42nKikloMQAdNZAghcZT
I8LEsNKMgNQiO36JiJMnhJbWHzVAwgWICYTCCqlUtMIBMLkc0joQwbTAibRE6sl8opIhhbA3PeDB
RKtBFfQpa12CZKHsqojFUg6uTrktJnaOCscnzfK6WOEYiwAawgJwMDMB8HQ1U+a0uMbjMXAbClFe
mdRZzB7mWUmSDAsrWik0LJqc6anzvtY0cw5vAbrw/sd90jvCSoMzN/0nlSDeDD7hpGR6dnhcUkAr
7SL/U2HZ90miPhSTEz/MJVpbIlmIuOLa2QZm7UfAQDvmXziwFqXmF11yHd3Ett2eU7/9M8ph5jJk
MWmXN/YePzpgEg8HPRH6UwsC8OScooZBcDEyCOIpHpVv9FPn2MumOxqQk2znbuAyKp9rWCGTeXks
YvlhwFryaiMr80Sx4tV4cX1HI5r9knkoAnUl1ceU+WBvPZkP3huRDmYFBkba4gQFoupoc1eJlQtV
+jQ2NKXHF7UKpI0+MTIYeD/W0OvQRzc4Xq44hW5DjvtK/z7oayq7Be48uRp+ENIr9u3B8yaKLNH1
XSA5gPkGGpkjyDDegkibgcI4nihgfA+hrwzic5FxOJ6a8jBhHBWHbQ32QgoIoNAiMi8jBDAyeD3P
WewVFKU0EmCjlv4BuF4gTqe2R6h7mgjWqVh/E9yij7pF62es2DvO703fBhgeosiW0N4pht3CaaOu
lNFYk43cHKSQ+fJ6qscoYRjmDLxEZQnk7MuuwEN3sXEDn+G0RAtAoHTQRYdQvqA/oA+4V/bTJwzg
HuOQPZ8Lsg4sEN/C0tWpqmH+BcixaA0mDLFdCAMD6ZTosI6FiI1DuB7BzCo+guC8p0d24imE4JAZ
E1DMZh4cI/IYVqL/i7kinChIc76bUwA=

[-- Attachment #3: Type: text/plain, Size: 14 bytes --]


Cheers,

Tom

bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'

[Stefan Monnier]

> Thanks for both your responses. I've attached the same patch with the
> simplification suggested by Drew. Whomever applies one can pick which
> they prefer.

Thanks, installed,


        Stefan