* bug#18478: 24.4.50; doc string of `clone-indirect-buffer'
@ 2014-09-14 22:14 Drew Adams
2014-09-17 22:49 ` bug#18478: [Patch] Mention the return value " Tom Willemse
0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2014-09-14 22:14 UTC (permalink / raw)
To: 18478
.. 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'
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-14 22:14 bug#18478: 24.4.50; doc string of `clone-indirect-buffer' Drew Adams
@ 2014-09-17 22:49 ` Tom Willemse
2014-09-17 22:55 ` Drew Adams
0 siblings, 1 reply; 9+ messages in thread
From: Tom Willemse @ 2014-09-17 22:49 UTC (permalink / raw)
To: 18478
[-- 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==
^ permalink raw reply [flat|nested] 9+ messages in thread* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-17 22:49 ` bug#18478: [Patch] Mention the return value " Tom Willemse
@ 2014-09-17 22:55 ` Drew Adams
2014-09-17 23:11 ` Tom Willemse
0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2014-09-17 22:55 UTC (permalink / raw)
To: Tom Willemse, 18478
> 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...".
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-17 22:55 ` Drew Adams
@ 2014-09-17 23:11 ` Tom Willemse
2014-09-18 1:47 ` Drew Adams
0 siblings, 1 reply; 9+ messages in thread
From: Tom Willemse @ 2014-09-17 23:11 UTC (permalink / raw)
To: Drew Adams; +Cc: 18478
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.
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-17 23:11 ` Tom Willemse
@ 2014-09-18 1:47 ` Drew Adams
2014-09-18 2:40 ` Stefan Monnier
0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2014-09-18 1:47 UTC (permalink / raw)
To: Tom Willemse; +Cc: 18478
> >> 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. ;-)
^ permalink raw reply [flat|nested] 9+ messages in thread
* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-18 1:47 ` Drew Adams
@ 2014-09-18 2:40 ` Stefan Monnier
2014-09-18 4:05 ` Drew Adams
0 siblings, 1 reply; 9+ messages in thread
From: Stefan Monnier @ 2014-09-18 2:40 UTC (permalink / raw)
To: Drew Adams; +Cc: 18478
>> 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.
^ permalink raw reply [flat|nested] 9+ messages in thread* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-18 2:40 ` Stefan Monnier
@ 2014-09-18 4:05 ` Drew Adams
2014-09-20 23:50 ` Tom Willemse
0 siblings, 1 reply; 9+ messages in thread
From: Drew Adams @ 2014-09-18 4:05 UTC (permalink / raw)
To: Stefan Monnier; +Cc: 18478
> > 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.
^ permalink raw reply [flat|nested] 9+ messages in thread* bug#18478: [Patch] Mention the return value of `clone-indirect-buffer'
2014-09-18 4:05 ` Drew Adams
@ 2014-09-20 23:50 ` Tom Willemse
2014-09-21 22:10 ` Stefan Monnier
0 siblings, 1 reply; 9+ messages in thread
From: Tom Willemse @ 2014-09-20 23:50 UTC (permalink / raw)
To: Drew Adams, Stefan Monnier; +Cc: 18478
[-- 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
^ permalink raw reply [flat|nested] 9+ messages in thread
end of thread, other threads:[~2014-09-21 22:10 UTC | newest]
Thread overview: 9+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2014-09-14 22:14 bug#18478: 24.4.50; doc string of `clone-indirect-buffer' Drew Adams
2014-09-17 22:49 ` bug#18478: [Patch] Mention the return value " Tom Willemse
2014-09-17 22:55 ` Drew Adams
2014-09-17 23:11 ` Tom Willemse
2014-09-18 1:47 ` Drew Adams
2014-09-18 2:40 ` Stefan Monnier
2014-09-18 4:05 ` Drew Adams
2014-09-20 23:50 ` Tom Willemse
2014-09-21 22:10 ` Stefan Monnier
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).