From: Tomi Ollila Date: Wed, 5 Jun 2013 06:05:43 +0000 (+0300) Subject: Re: [PATCH] emacs: remove hardcoded defaults values from docstrings X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=fb5924bc05eeaf591381f53df74197bcd14464a0;p=notmuch-archives.git Re: [PATCH] emacs: remove hardcoded defaults values from docstrings --- diff --git a/18/29b05ed62d69566029bd13a58413544dfd1f44 b/18/29b05ed62d69566029bd13a58413544dfd1f44 new file mode 100644 index 000000000..7a2ec6701 --- /dev/null +++ b/18/29b05ed62d69566029bd13a58413544dfd1f44 @@ -0,0 +1,101 @@ +Return-Path: +X-Original-To: notmuch@notmuchmail.org +Delivered-To: notmuch@notmuchmail.org +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