From mboxrd@z Thu Jan 1 00:00:00 1970 Received: from eggs.gnu.org ([2001:4830:134:3::10]:34572) by lists.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9d6i-0002q9-Kj for qemu-devel@nongnu.org; Thu, 17 Dec 2015 13:16:53 -0500 Received: from Debian-exim by eggs.gnu.org with spam-scanned (Exim 4.71) (envelope-from ) id 1a9d6d-0007Aj-LF for qemu-devel@nongnu.org; Thu, 17 Dec 2015 13:16:52 -0500 Received: from mx1.redhat.com ([209.132.183.28]:37911) by eggs.gnu.org with esmtp (Exim 4.71) (envelope-from ) id 1a9d6d-0007AY-6S for qemu-devel@nongnu.org; Thu, 17 Dec 2015 13:16:47 -0500 Received: from int-mx14.intmail.prod.int.phx2.redhat.com (int-mx14.intmail.prod.int.phx2.redhat.com [10.5.11.27]) by mx1.redhat.com (Postfix) with ESMTPS id D5B54113719 for ; Thu, 17 Dec 2015 18:16:46 +0000 (UTC) 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> From: Eric Blake Message-ID: <5672FC0D.70300@redhat.com> Date: Thu, 17 Dec 2015 11:16:45 -0700 MIME-Version: 1.0 In-Reply-To: <87wpsduf2i.fsf@blackfin.pond.sub.org> Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="rKW5Vqv2DDfOM1PTLWiBIq2SJxogmuRqR" 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: Markus Armbruster Cc: qemu-devel@nongnu.org This is an OpenPGP/MIME signed message (RFC 4880 and 3156) --rKW5Vqv2DDfOM1PTLWiBIq2SJxogmuRqR Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable 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. >=20 > I'll fix this example. >=20 >>> + * >>> + * Do *not* contract this to >>> + * error_setg(&err, "invalid quark\n" >>> + * "Valid quarks are up, down, strange, charm, top, b= ottom"); Of course, if you put a trailing dot above, you'd also want it here in the 'don't contract' section. >>> @@ -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? >=20 > Yes. How to best phrase it? Maybe: The resulting message should be a single phrase, with no newline or trailing punctuation. >=20 >> Should we also mention no need for leading 'error: ' prefix? >=20 > 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 e= rror. >>> - * 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. >=20 > You mean "not &error_abort or &error_abort"? Yes, that works: @errp may be NULL, but not &error_fatal or &error_abort. --=20 Eric Blake eblake redhat com +1-919-301-3266 Libvirt virtualization library http://libvirt.org --rKW5Vqv2DDfOM1PTLWiBIq2SJxogmuRqR Content-Type: application/pgp-signature; name="signature.asc" Content-Description: OpenPGP digital signature Content-Disposition: attachment; filename="signature.asc" -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 Comment: Public key at http://people.redhat.com/eblake/eblake.gpg Comment: Using GnuPG with Thunderbird - http://www.enigmail.net/ iQEcBAEBCAAGBQJWcvwOAAoJEKeha0olJ0NqyHwH/0w3QUTarSI5JYvqdsSnT28m hGoklo1g9wqGG9yozDg9VXSYe6hwcbBe4vKRpHEcXNk/VxR5xfpcxKi98nT/8ySI MI6zMqR4Y5TaHDyDIyXpVbQGDkAZICAtAFipchchO1nLxM9YTMgK238sRFoIy8q8 pN3FeLAAEYF09lJqwm/JWR6CPeUiLApOTxo/utkuzjXbLlXBeKRuGkb+CVrlQWLW 9eoaOz+cyJsOpeDonuXWCdbkaZjbJWbA7PcNYzfaPMW0N8DCHRHaa+C+TSP06kxA IPnMb3bHI79U8MGfpwqc3IRZ7Soe4qgnYsB0PPprC7OG91447nFvOjneC8+M0ek= =OOkT -----END PGP SIGNATURE----- --rKW5Vqv2DDfOM1PTLWiBIq2SJxogmuRqR--