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