Return-Path: <kfogel@gmail.com>
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 792F0431FBD
	for <notmuch@notmuchmail.org>; Mon,  7 Jul 2014 10:40:44 -0700 (PDT)
X-Virus-Scanned: Debian amavisd-new at olra.theworths.org
X-Spam-Flag: NO
X-Spam-Score: -0.699
X-Spam-Level: 
X-Spam-Status: No, score=-0.699 tagged_above=-999 required=5
	tests=[DKIM_SIGNED=0.1, DKIM_VALID=-0.1, FREEMAIL_FROM=0.001,
	RCVD_IN_DNSWL_LOW=-0.7] 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 xr+nYA+f43ff for <notmuch@notmuchmail.org>;
	Mon,  7 Jul 2014 10:40:37 -0700 (PDT)
Received: from mail-ie0-f181.google.com (mail-ie0-f181.google.com
	[209.85.223.181]) (using TLSv1 with cipher RC4-SHA (128/128 bits))
	(No client certificate requested)
	by olra.theworths.org (Postfix) with ESMTPS id 4AF98431FBC
	for <notmuch@notmuchmail.org>; Mon,  7 Jul 2014 10:40:37 -0700 (PDT)
Received: by mail-ie0-f181.google.com with SMTP id y20so3782253ier.26
	for <notmuch@notmuchmail.org>; Mon, 07 Jul 2014 10:40:37 -0700 (PDT)
DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113;
	h=sender:from:to:cc:subject:references:reply-to:date:in-reply-to
	:message-id:user-agent:mime-version:content-type;
	bh=9b82qzGQy3zFwSWJs6mW34QgQJmHcf8EpcHcduLdzFY=;
	b=lQsndor4PC2Yk25g7qwpNY6M+x+VavVrCEWh+P+P4dWzzVgVCpJXN8SZRuGzN+yvJl
	bs3D7M4D45j1qphxMTPfrxL7aRpvnCEOmH14nR3D0BRWcAg7qoZ2KqqK7r4sKsnp3CVt
	cxiW0xpDh4j60MzF5Eu0RkLJp17Lr8bs/EaswtF5t5feBazUG5I6X/ivwIDjlVKRuOd0
	U4MbwIwuESYJHD7OGY68/e2LxjTLBKjfIT6t58xFwvPfiUTySqUi5eB6Yr8D/04/LeKq
	svEglyBhUTuUuGEIOR68nvhf/Doikp700Xfjh2K/buKxMiinqr+EEU6IfGuIv+UAGoPm
	Nx4w==
X-Received: by 10.42.106.15 with SMTP id x15mr4713949ico.67.1404754836932;
	Mon, 07 Jul 2014 10:40:36 -0700 (PDT)
Received: from ktab.red-bean.com
	(74-92-190-113-Illinois.hfc.comcastbusiness.net. [74.92.190.113])
	by mx.google.com with ESMTPSA id ys2sm2699476igb.6.2014.07.07.10.40.35
	for <multiple recipients>
	(version=TLSv1.2 cipher=RC4-SHA bits=128/128);
	Mon, 07 Jul 2014 10:40:36 -0700 (PDT)
Sender: Karl Fogel <kfogel@gmail.com>
From: Karl Fogel <kfogel@red-bean.com>
To: Sebastian Lipp <bacuh@riseup.net>
Subject: Re: [PATCH] emacs: add missing paren to fix defun in
	notmuch-address.el.
References: <87wqsfik5l.fsf@floss.red-bean.com>
	<87mwtah2hd.fsf@zancas.localnet> <877gkeau42.fsf@floss.red-bean.com>
	<m2ppy5v3mc.fsf@guru.guru-group.fi> <8738v1jtzc.fsf@nikula.org>
	<87k3odgutd.fsf@zancas.localnet> <87ip3wbj7g.fsf@mcs.anl.gov>
	<m2hajgxli5.fsf@guru.guru-group.fi> <87vc7vgbym.fsf@zancas.localnet>
	<m2ehejykb1.fsf@guru.guru-group.fi>
	<87pphmc604.fsf@verb.i-did-not-set--mail-host-address--so-tickle-me>
	<87oax6vt4u.fsf@ktab.red-bean.com>
	<87bnt2dy0b.fsf@verb.i-did-not-set--mail-host-address--so-tickle-me>
Date: Mon, 07 Jul 2014 12:40:35 -0500
In-Reply-To:
 <87bnt2dy0b.fsf@verb.i-did-not-set--mail-host-address--so-tickle-me>
	(Sebastian Lipp's message of "Sun, 06 Jul 2014 22:37:40 +0200")
Message-ID: <87y4w5jcdo.fsf@ktab.red-bean.com>
User-Agent: Gnus/5.13 (Gnus v5.13) Emacs/24.4.50 (gnu/linux)
MIME-Version: 1.0
Content-Type: text/plain
Cc: Tomi Ollila <tomi.ollila@iki.fi>, notmuch@notmuchmail.org
X-BeenThere: notmuch@notmuchmail.org
X-Mailman-Version: 2.1.13
Precedence: list
Reply-To: Karl Fogel <kfogel@red-bean.com>
List-Id: "Use and development of the notmuch mail system."
	<notmuch.notmuchmail.org>
List-Unsubscribe: <http://notmuchmail.org/mailman/options/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=unsubscribe>
List-Archive: <http://notmuchmail.org/pipermail/notmuch>
List-Post: <mailto:notmuch@notmuchmail.org>
List-Help: <mailto:notmuch-request@notmuchmail.org?subject=help>
List-Subscribe: <http://notmuchmail.org/mailman/listinfo/notmuch>,
	<mailto:notmuch-request@notmuchmail.org?subject=subscribe>
X-List-Received-Date: Mon, 07 Jul 2014 17:40:44 -0000

Sebastian Lipp <bacuh@riseup.net> writes:
>> I think it's good to include an initial value (even an invalid
>> placeholder one, if the real initialization has not happened yet), and a
>> doc string.  C-h f defvar RET will say more about how to do that.
>
>I hope I got that right now. (I've got no real clue of Lisp yet because
>I just recently switched to emacs partly because of notmuch. :)
>
>How about
>
>    (defvar bbdb-get-addresses-headers nil
>      "List of Addresses to import into bbdb")

That's interesting -- from seeing the variable's name, I would not have
guessed that it is a list.

Can the doc string describe the exact format of the list, and something
about how the list is initialized and used?

In other words, if you were a programmer seeing this variable for the
first time, and you had only a basic working knowledge of what the
notmuch Elisp code does, what would you want to see in this doc string
to give you a good understanding of what this variable is, how it gets
set, and how it's used?

One test I often use for myself is that if after I've read the doc
string, I can look at any value and say whether or not it is a valid
value that this variable might hold (when the code is running), then the
doc string has done its job.

Best,
-Karl