From 43a05ea36331a3463efd33e3a6cbbc3d723f36e5 Mon Sep 17 00:00:00 2001
From: Panu Matilainen <pmatilai@redhat.com>
Date: Wed, 2 Jul 2008 14:24:20 +0300
Subject: [PATCH] Add documentation for keyring

---
 doc/hacking/Doxyheader |  2 ++
 doc/librpm/Doxyheader  |  2 ++
 rpmio/rpmkeyring.h     | 44 ++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 48 insertions(+)

diff --git a/doc/hacking/Doxyheader b/doc/hacking/Doxyheader
index d762708..0b254d0 100644
--- a/doc/hacking/Doxyheader
+++ b/doc/hacking/Doxyheader
@@ -24,6 +24,8 @@
  */
 /** \defgroup  rpmps   Problem Set API.
  */
+/** \defgroup	rpmkeyring	RPM keyring API.
+ */
 /** \defgroup	rpmgi	Generalized Iterator API.
  */
 /** \defgroup	rpmmacro	Macro API.
diff --git a/doc/librpm/Doxyheader b/doc/librpm/Doxyheader
index cb2fdad..a46c753 100644
--- a/doc/librpm/Doxyheader
+++ b/doc/librpm/Doxyheader
@@ -20,6 +20,8 @@
  */
 /** \defgroup	rpmps	Problem Set API.
  */
+/** \defgroup	rpmkeyring	RPM keyring API.
+ */
 /** \defgroup	rpmgi	Generalized Iterator API.
  */
 /** \defgroup	rpmmacro	Macro API.
diff --git a/rpmio/rpmkeyring.h b/rpmio/rpmkeyring.h
index 47b1a96..234128d 100644
--- a/rpmio/rpmkeyring.h
+++ b/rpmio/rpmkeyring.h
@@ -1,17 +1,61 @@
 #ifndef _RPMKEYRING_H
 #define _RPMKEYRING_H
 
+/** \ingroup rpmkeyring
+ * \file rpmio/rpmkeyring.h
+ */
+
 #include <rpm/rpmtypes.h>
 #include <rpm/rpmpgp.h>
 
+/** \ingroup rpmkeyring
+ * Create a new, empty keyring
+ * @return	new keyring handle
+ */
 rpmKeyring rpmKeyringNew(void);
+
+/** \ingroup rpmkeyring
+ * Free keyring and the keys within it
+ * @return	NULL always
+ */
 rpmKeyring rpmKeyringFree(rpmKeyring keyring);
+
+/** \ingroup rpmkeyring
+ * Add a public key to keyring.
+ * @param keyring	keyring handle
+ * @param key		pubkey handle
+ * @return		0 on success, -1 on error, 1 if key already present
+ */
 int rpmKeyringAddKey(rpmKeyring keyring, rpmPubkey key);
 
+/** \ingroup rpmkeyring
+ * Perform keyring lookup for a key matching a signature
+ * @param keyring	keyring handle
+ * @param sig		OpenPGP packet container of signature
+ * @return		RPMRC_OK if found, RPMRC_NOKEY otherwise
+ */
 rpmRC rpmKeyringLookup(rpmKeyring keyring, pgpDig sig);
 
+/** \ingroup rpmkeyring
+ * Create a new rpmPubkey from OpenPGP packet
+ * @param pkt		OpenPGP packet data
+ * @param pktlen	Data length
+ * @return		new pubkey handle
+ */
 rpmPubkey rpmPubkeyNew(const uint8_t *pkt, size_t pktlen);
+
+/** \ingroup rpmkeyring
+ * Create a new rpmPubkey from ASCII-armored pubkey file
+ * @param filename	Path to pubkey file
+ * @return		new pubkey handle
+ */
 rpmPubkey rpmPubkeyRead(const char *filename);
+
+/** \ingroup rpmkeyring
+ * Free a pubkey.
+ * @param key		Pubkey to free
+ * @return		NULL always
+ */
 rpmPubkey rpmPubkeyFree(rpmPubkey key);
 
 #endif /* _RPMKEYDB_H */
-- 
2.7.4