Received: from eggs.gnu.org ([2001:4830:134:3::10]:47798) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9dmr-0003e2-Jm for qemu-devel@nongnu.org; Thu, 17 Dec 2015 14:00:31 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9dmm-0001in-Kh for qemu-devel@nongnu.org; Thu, 17 Dec 2015 14:00:25 -0500 Received: from mx1.redhat.com ([209.132.183.28]:35258) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9dmm-0001iY-FT for qemu-devel@nongnu.org; Thu, 17 Dec 2015 14:00:20 -0500 Received: from int-mx10.intmail.prod.int.phx2.redhat.com (int-mx10.intmail.prod.int.phx2.redhat.com [10.5.11.23]) by mx1.redhat.com (Postfix) with ESMTPS id 0FA33C00354F for ; Thu, 17 Dec 2015 19:00:20 +0000 (UTC) From: Markus Armbruster References: <1450371004-26866-1-git-send-email-armbru@redhat.com> <1450371004-26866-6-git-send-email-armbru@redhat.com> <5672E9E5.70004@redhat.com> <87wpsduf2i.fsf@blackfin.pond.sub.org> <5672FC0D.70300@redhat.com> Date: Thu, 17 Dec 2015 20:00:17 +0100 In-Reply-To: <5672FC0D.70300@redhat.com> (Eric Blake's message of "Thu, 17 Dec 2015 11:16:45 -0700") Message-ID: <87mvt8rjcu.fsf@blackfin.pond.sub.org> MIME-Version: 1.0 Content-Type: text/plain Subject: Re: [Qemu-devel] [PATCH v2 05/23] error: Improve documentation around error_append_hint() List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , To: Eric Blake Cc: qemu-devel@nongnu.org Eric Blake writes: > On 12/17/2015 11:04 AM, Markus Armbruster wrote: > >>>> + * Create an error and add additional explanation: >>>> + * error_setg(&err, "invalid quark"); >>>> + * error_append_hint(&err, "Valid quarks are up, down, strange, " >>>> + * "charm, top, bottom\n"); >>> >>> Do we want to allow/encourage a trailing dot in the hint? I'm fine if >>> we don't - but once we document its usage, we should probably then be >>> consistent with what we document; qemu-option.c used a trailing dot, >>> qdev-monitor.c did not. >> >> I'll fix this example. >> >>>> + * >>>> + * Do *not* contract this to >>>> + * error_setg(&err, "invalid quark\n" >>>> + * "Valid quarks are up, down, strange, charm, top, bottom"); > > Of course, if you put a trailing dot above, you'd also want it here in > the 'don't contract' section. Yes. >>>> @@ -128,6 +138,7 @@ ErrorClass error_get_class(const Error *err); >>>> * If @errp is anything else, *@errp must be NULL. >>>> * The new error's class is ERROR_CLASS_GENERIC_ERROR, and its >>>> * human-readable error message is made from printf-style @fmt, ... >>>> + * The resulting message should not contain newlines. >>> >>> Should we also discourage trailing punctuation? >> >> Yes. How to best phrase it? > > Maybe: > > The resulting message should be a single phrase, with no newline or > trailing punctuation. What about ending the message with an exclamation mark? >>> Should we also mention no need for leading 'error: ' prefix? >> >> Unlike the other anti-patterns, this one doesn't seem frequent in new >> code. > > Fair enough. > > >>>> /** >>>> * Append a printf-style human-readable explanation to an existing error. >>>> - * May be called multiple times, and safe if @errp is NULL. >>>> + * @errp may be NULL, but neither &error_fatal nor &error_abort. >>> >>> As a native speaker, 'not' sounds better than 'neither' in that >>> sentence. But I think both choices are grammatically correct. >> >> You mean "not &error_abort or &error_abort"? > > Yes, that works: > > @errp may be NULL, but not &error_fatal or &error_abort.