Clarify what "checking on bit" means
authorAndre Heinecke <aheinecke@intevation.de>
Wed, 7 Dec 2016 20:41:34 +0000 (21:41 +0100)
committerAndre Heinecke <aheinecke@intevation.de>
Wed, 7 Dec 2016 20:46:24 +0000 (21:46 +0100)
* doc/gpgme.texi (gpgme_sigsum_t summary): Clarify what "you
can check one bit means"

--
It was unclear which bit to test for is. And tests
with students have shown that they would "test" for
this one bit by using if(sig.summary == GPGME_SIGSUM_VALID)
which would fail because valid sigs are also SIGSUM_GREEN.

So lets give an example for people not used to checking bits and
clarify through this example which bit is meant to be checked.

doc/gpgme.texi

index 32e0861..ee82b27 100644 (file)
@@ -4948,7 +4948,19 @@ list, or @code{NULL} if this is the last element.
 This is a bit vector giving a summary of the signature status.  It
 provides an easy interface to a defined semantic of the signature
 status.  Checking just one bit is sufficient to see whether a
-signature is valid without any restrictions.
+signature is valid without any restrictions. This means that
+you can check for GPGME_SIGSUM_VALID like this:
+
+@example
+if (sig.summary & GPGME_SIGSUM_VALID)
+@{
+   ..do stuff if valid..
+@}
+else
+@{
+   ..do stuff if not fully valid..
+@}
+@end example
 
 The defined bits are:
   @table @code