More API documentation. The main change in this lot is to

ensure that every header file is documented. That avoids 
ugly results in the "files" tab in the HTML, and also
identifies some undocumented functions - also fixed.

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

include/QtCrypto/qca.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca.h
+
+   Summary header file for %QCA.
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_H
 #define QCA_H
 

include/QtCrypto/qca_basic.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_basic.h
+
+   Header file for classes for cryptographic primitives (basic operations)
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_BASIC_H
 #define QCA_BASIC_H
 

include/QtCrypto/qca_cert.h

@@ -1,7 +1,7 @@
 /*
  * qca_cert.h - Qt Cryptographic Architecture
  * Copyright (C) 2003-2005  Justin Karneges <justin@affinix.com>
- * Copyright (C) 2004,2005  Brad Hards <bradh@frogmouth.net>
+ * Copyright (C) 2004 - 2006  Brad Hards <bradh@frogmouth.net>
  *
  * This library is free software; you can redistribute it and/or
  * modify it under the terms of the GNU Lesser General Public
@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_cert.h
+
+   Header file for PGP key and X.509 certificate related classes
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_CERT_H
 #define QCA_CERT_H
 

include/QtCrypto/qca_core.h

@@ -19,9 +19,22 @@
  *
  */
 
+/**
+   \file qca_core.h
+
+   Header file for core %QCA infrastructure
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_CORE_H
 #define QCA_CORE_H
 
+/**
+   The current version of %QCA
+*/
 #define QCA_VERSION 0x020000
 
 #include <QString>

include/QtCrypto/qca_export.h

@@ -18,11 +18,28 @@
  *
  */
 
+/**
+   \file qca_export.h
+
+   Preprocessor magic to allow export of library symbols.
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_EXPORT_H
 #define QCA_EXPORT_H
 
 #include <QtGlobal>
 
+/**
+   \def QCA_EXPORT 
+
+   \internal
+
+   Makes this QCA symbol visible.
+*/
 #ifdef Q_OS_WIN32
 # ifndef QCA_STATIC
 #  ifdef QCA_MAKEDLL
@@ -36,6 +53,13 @@
 # define QCA_EXPORT
 #endif
 
+/**
+   \def QCA_PLUGIN_EXPORT 
+
+   \internal
+
+   Makes this symbol from a plugin visible.
+*/
 #ifdef Q_OS_WIN32
 # ifdef QCA_PLUGIN_DLL
 #  define QCA_PLUGIN_EXPORT extern "C" __declspec(dllexport)

include/QtCrypto/qca_keystore.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_keystore.h
+
+   Header file for classes that provide and manage keys
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_KEYSTORE_H
 #define QCA_KEYSTORE_H
 

include/QtCrypto/qca_publickey.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_publickey.h
+
+   Header file for PublicKey and PrivateKey related classes
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_PUBLICKEY_H
 #define QCA_PUBLICKEY_H
 

include/QtCrypto/qca_securelayer.h

@@ -19,6 +19,15 @@
  *
  */
 
+/**
+   \file qca_securelayer.h
+
+   Header file for SecureLayer and its subclasses
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
 #ifndef QCA_SECURELAYER_H
 #define QCA_SECURELAYER_H
 
@@ -203,6 +212,21 @@ namespace QCA
 	   \class TLS qca_securelayer.h QtCrypto
 
 	   Transport Layer Security / Secure Socket Layer 
+
+	   Transport Layer Security (%TLS) is the current
+	   state-of-the-art in secure transport mechanisms over the
+	   internet. It can be used in a way where only one side of
+	   the link needs to authenticate to the other. This makes it
+	   very useful for servers to provide their identity to
+	   clients. Note that is is possible to use %TLS to
+	   authenticate both client and server.
+
+	   %TLS is a IETF standard (<a
+	   href="http://www.ietf.org/rfc/rfc2712.txt">RFC2712</a> for
+	   TLS version 1.0) based on earlier Netscape work on Secure
+	   Socket Layer (SSL version 2 and SSL version 3). New
+	   applications should use at least TLS 1.0, and SSL version 2
+	   should be avoided due to known security problems.
 	*/
 	class QCA_EXPORT TLS : public SecureLayer, public Algorithm
 	{

include/QtCrypto/qca_securemessage.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_securemessage.h
+
+   Header file for secure message (PGP, CMS) classes
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_SECUREMESSAGE_H
 #define QCA_SECUREMESSAGE_H
 

include/QtCrypto/qca_support.h

@@ -19,6 +19,19 @@
  *
  */
 
+/**
+   \file qca_support.h
+
+   Header file for "support" classes used in %QCA
+
+   The classes in this header do not have any cryptographic
+   content - they are used in %QCA, and are included for convenience. 
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_SUPPORT_H
 #define QCA_SUPPORT_H
 

include/QtCrypto/qca_textfilter.h

@@ -19,6 +19,16 @@
  *
  */
 
+/**
+   \file qca_textfilter.h
+
+   Header file for text encoding/decoding classes
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_TEXTFILTER_H
 #define QCA_TEXTFILTER_H
 

include/QtCrypto/qca_tools.h

@@ -19,6 +19,19 @@
  *
  */
 
+/**
+   \file qca_tools.h
+
+   Header file for "tool" classes used in %QCA
+
+   These classes differ from those in qca_support.h, in that they have
+   some cryptographic relationship, and require secure memory.
+
+   \Note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QCA_TOOLS_H
 #define QCA_TOOLS_H
 
@@ -30,9 +43,32 @@ class QString;
 class QByteArray;
 class QTextStream;
 
-// Direct secure memory access.  For interfacing with C libraries if needed.
+/**
+   Allocate a block of memory from the secure memory pool.
+
+   This is intended to be used when working with C libraries.
+
+   \param bytes the number of bytes to allocate
+*/
 QCA_EXPORT void *qca_secure_alloc(int bytes);
+
+/**
+   Free (de-allocate) a block of memory that has been previously
+   allocated from the secure memory pool.
+
+   This is intended to be used when working with C libraries.
+
+   \param p pointer to the block of memory to be free'd
+*/
 QCA_EXPORT void qca_secure_free(void *p);
+
+/**
+   Resize (re-allocate) a block of memory that has been previously
+   allocated from the secure memory pool.
+
+   \param p pointer to the block of memory to be resized.
+   \param bytes the new size that is required.
+*/
 QCA_EXPORT void *qca_secure_realloc(void *p, int bytes);
 
 /**

include/QtCrypto/qpipe.h

@@ -17,6 +17,16 @@
  *
  */
 
+/**
+   \file qpipe.h
+
+   Header file for the QPipe FIFO class
+
+   \note You should not use this header directly from an
+   application. You should just use <tt> \#include \<QtCrypto>
+   </tt> instead.
+*/
+
 #ifndef QPIPE_H
 #define QPIPE_H