Re: [PATCH] emacs: remove hardcoded defaults values from docstrings

diff --git a/18/29b05ed62d69566029bd13a58413544dfd1f44 b/18/29b05ed62d69566029bd13a58413544dfd1f44
new file mode 100644 (file)
index 0000000..7a2ec67
--- /dev/null
+++ b/18/29b05ed62d69566029bd13a58413544dfd1f44
@@ -0,0 +1,101 @@
+Return-Path: <tomi.ollila@iki.fi>\r
+X-Original-To: notmuch@notmuchmail.org\r
+Delivered-To: notmuch@notmuchmail.org\r
+Received: from localhost (localhost [127.0.0.1])\r
+       by olra.theworths.org (Postfix) with ESMTP id 11EBB431FAF\r
+       for <notmuch@notmuchmail.org>; Tue,  4 Jun 2013 23:06:12 -0700 (PDT)\r
+X-Virus-Scanned: Debian amavisd-new at olra.theworths.org\r
+X-Spam-Flag: NO\r
+X-Spam-Score: 0\r
+X-Spam-Level: \r
+X-Spam-Status: No, score=0 tagged_above=-999 required=5 tests=[none]\r
+       autolearn=disabled\r
+Received: from olra.theworths.org ([127.0.0.1])\r
+       by localhost (olra.theworths.org [127.0.0.1]) (amavisd-new, port 10024)\r
+       with ESMTP id 36hX1goAjTcJ for <notmuch@notmuchmail.org>;\r
+       Tue,  4 Jun 2013 23:05:49 -0700 (PDT)\r
+Received: from guru.guru-group.fi (guru.guru-group.fi [46.183.73.34])\r
+       by olra.theworths.org (Postfix) with ESMTP id 97695431FAE\r
+       for <notmuch@notmuchmail.org>; Tue,  4 Jun 2013 23:05:49 -0700 (PDT)\r
+Received: from guru.guru-group.fi (localhost [IPv6:::1])\r
+       by guru.guru-group.fi (Postfix) with ESMTP id 41B03100030;\r
+       Wed,  5 Jun 2013 09:05:44 +0300 (EEST)\r
+From: Tomi Ollila <tomi.ollila@iki.fi>\r
+To: David Bremner <david@tethera.net>, Austin Clements <amdragon@MIT.EDU>\r
+Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings\r
+In-Reply-To: <87haheq7kq.fsf@zancas.localnet>\r
+References: <1370181885-23021-1-git-send-email-david@tethera.net>\r
+       <20130604040102.GJ5999@mit.edu> <m2ppw275hs.fsf@guru.guru-group.fi>\r
+       <8738syrtsy.fsf@zancas.localnet> <20130604133738.GL5999@mit.edu>\r
+       <87haheq7kq.fsf@zancas.localnet>\r
+User-Agent: Notmuch/0.15.2+172~g0a61aef (http://notmuchmail.org) Emacs/24.3.1\r
+       (x86_64-unknown-linux-gnu)\r
+X-Face: HhBM'cA~<r"^Xv\KRN0P{vn'Y"Kd;zg_y3S[4)KSN~s?O\"QPoL\r
+       $[Xv_BD:i/F$WiEWax}R(MPS`^UaptOGD`*/=@\1lKoVa9tnrg0TW?"r7aRtgk[F\r
+       !)g;OY^,BjTbr)Np:%c_o'jj,Z\r
+Date: Wed, 05 Jun 2013 09:05:43 +0300\r
+Message-ID: <m2vc5thz2g.fsf@guru.guru-group.fi>\r
+MIME-Version: 1.0\r
+Content-Type: text/plain\r
+Cc: notmuch@notmuchmail.org\r
+X-BeenThere: notmuch@notmuchmail.org\r
+X-Mailman-Version: 2.1.13\r
+Precedence: list\r
+List-Id: "Use and development of the notmuch mail system."\r
+       <notmuch.notmuchmail.org>\r
+List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>\r
+List-Archive: <http://notmuchmail.org/pipermail/notmuch>\r
+List-Post: <mailto:notmuch@notmuchmail.org>\r
+List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>\r
+List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,\r
+       <mailto:notmuch-request@notmuchmail.org?subject=subscribe>\r
+X-List-Received-Date: Wed, 05 Jun 2013 06:06:12 -0000\r
+\r
+On Tue, Jun 04 2013, David Bremner <david@tethera.net> wrote:\r
+\r
+> Austin Clements <amdragon@MIT.EDU> writes:\r
+>>\r
+>> Right.  I think we should both reference the variable and say what the\r
+>> default behavior is (there's no reason not to do both).  But isn't\r
+>> that what these docstrings used to do?\r
+>\r
+> Looking at the old docstrings in notmuch-show.el, I agree they basically\r
+> implement Tomi's suggestion.  While I think copying default values of\r
+> variables into docstrings creates some minor maintainability traps\r
+> (since we then need to remember to look at all the places a variable is\r
+> referenced if we change the default value), I'm willing to revert the\r
+> patch if people think the tradeoff of better usability is worth it.\r
+\r
+Well, revert would be the worst option -- maintainability traps there\r
+and no reference to the variable used ;/\r
+\r
+So either what we currently have in repository (and merge Mark's similar\r
+patches) or have both. In addition to my quick suggestion, what is been\r
+seen in notmuch-show.el docstrings this is what `split-string' has:\r
+\r
+...\r
+If SEPARATORS is non-nil, it should be a regular expression matching text\r
+which separates, but is not part of, the substrings.  If nil it defaults to\r
+`split-string-default-separators', normally "[ \f\t\n\r\v]+", and\r
+OMIT-NULLS is forced to t.\r
+...\r
+\r
+By looking the code, doc hardcoded, defconst split-string-default-separators\r
+-- from maintainability point of view those are close to each other...\r
+\r
+IMO what we currently have is OK, unless SomeOne(tm) provides a neat patch\r
+and agrees that maintainability is not really a problem here :D\r
+\r
+> It is unfortunate emacs doesn't provide a way to expand the current\r
+> value of a variable in the help string, but there we are. It probably\r
+> wouldn't be as easy to understand as hand crafted text in any case.\r
+\r
+We could have placeholders in *.el files and tune byte compiler\r
+to fill in the docstrings >;) Imagine the added bonus we get by\r
+the confusion that causes !\r
+\r
+\r
+> d\r
+\r
+Tomi\r