API documentation enhancements.

svn path=/trunk/kdesupport/qca/; revision=670417

include/QtCrypto/qca_core.h

@@ -679,7 +679,7 @@ QStringList features() const
 	QStringList list;
 	list += "sha1";
 	list += "sha256";
-	list += "hmac(md5)";
+	list += "hmac(sha1)";
 	return list;
 }
 	   \endcode
@@ -723,7 +723,39 @@ Context *createContext(const QString &type)
 	*/
 	virtual Context *createContext(const QString &type) = 0;
 
+	/**
+	   Method to set up the default configuration options.
+
+	   If your provider needs some configuration options,
+	   this method allows you to establish default options.
+	   The user can then change the configuration options 
+	   as required, and set them using configChanged().
+
+	   You need to return a QVariantMap that has configuration
+	   options as the keys, and the default configuration 
+	   as the values, as shown below:
+	   \code
+QVariantMap defaultConfig() const
+{
+	QVariantMap myConfig;
+	myConfig[ "firstOption" ] = QString("firstOptionValue");
+	myConfig[ "secondOption" ] = true;
+	myConfig[ "thirdOpt" ] = 1243;
+	return myConfig;
+}
+	   \endcode
+
+	   \sa configChanged for how to set the configuration;
+	*/
 	virtual QVariantMap defaultConfig() const;
+
+	/**
+	   Method to set the configuration options.
+
+	   If your provider supports configuration options, you
+	   will be advised of user changes to the configuration 
+	   when this method is called.
+	*/
 	virtual void configChanged(const QVariantMap &config);
 };
 
@@ -775,7 +807,11 @@ protected:
 	*/
 	Context(Provider *parent, const QString &type);
 
-	// copy constructor
+	/**
+	   Copy constructor
+
+	   \param from the Context to copy from
+	*/
 	Context(const Context &from);
 
 private:

include/QtCrypto/qca_keystore.h

@@ -519,20 +519,84 @@ namespace QCA
 		friend class KeyStoreManagerPrivate;
 	};
 
-	// holds key store information outside of a keystore object
+	/**
+	   Key store information, outside of a KeyStore object
+
+	   This class is used in conjunction with the Event class,
+	   and related classes such as PasswordAsker and TokenAsker,
+	   to describe the key store source of the Event.
+
+	   Each KeyStoreInfo represents a single KeyStore, and describes
+	   the type of store (e.g. smartcard or PGP keyring - see 
+	   KeyStore::Type), and a couple of names. The id() of a KeyStore
+	   is used to reference it, and is typically of the form 
+	   "qca-mystorename". The name() of a KeyStore is used to describe
+	   it (i.e. this is the "pretty" name to show the user), and is
+	   typically of the form "My Store Name".
+	*/
 	class QCA_EXPORT KeyStoreInfo
 	{
 	public:
+		/**
+		   Constructor.
+
+		   \note This form of constructor for KeyStoreInfo
+		   produces an object that does not describe any 
+		   KeyStore, and isNull() will return true.
+		*/
 		KeyStoreInfo();
+
+		/**
+		   Standard constructor.
+
+		   This builds a KeyStoreInfo object that descibes a
+		   KeyStore.
+
+		   \param type the type of KeyStore
+		   \param id the identification of the KeyStore
+		   \param name the descriptive name of the KeyStore
+		*/
 		KeyStoreInfo(KeyStore::Type type, const QString &id, const QString &name);
+
+		/**
+		   Copy constructor.
+
+		   \param from the KeyStoreInfo to copy from
+		*/
 		KeyStoreInfo(const KeyStoreInfo &from);
+
 		~KeyStoreInfo();
+
+		/**
+		   Assignment operator.
+
+		   \param from the KeyStoreInfo to copy from
+		*/
 		KeyStoreInfo & operator=(const KeyStoreInfo &from);
 
+		/**
+		   Test if this object is valid
+
+		   \return true if the object is not valid
+		*/
 		bool isNull() const;
 
+		/**
+		   The Type of KeyStore that this KeyStoreInfo object
+		   describes.
+		*/
 		KeyStore::Type type() const;
+
+		/**
+		   The unique identification of the KeyStore that
+		   this KeyStoreInfo object describes.
+		*/
 		QString id() const;
+
+		/**
+		   The descriptive name of the KeyStore that this
+		   KeyStoreInfo object describes.
+		*/
 		QString name() const;
 
 	private: