Doxygen comments

7 files changed, 133 insertions, 11 deletions

diff --git a/src/libstate/libstate.h b/src/libstate/libstate.h
index b260a5bb9..a70fd3265 100644
--- a/src/libstate/libstate.h
+++ b/src/libstate/libstate.h
@@ -19,8 +19,8 @@
 
 namespace Botan {
 
-/*
-* Global State Container Base
+/**
+* Global Library State
 */
 class BOTAN_DLL Library_State
    {
diff --git a/src/math/mp/mp_core.h b/src/math/mp/mp_core.h
index 82bdbad53..c879f42ee 100644
--- a/src/math/mp/mp_core.h
+++ b/src/math/mp/mp_core.h
@@ -19,30 +19,49 @@ const size_t MP_WORD_BITS = BOTAN_MP_WORD_BITS;
 
 extern "C" {
 
-/*
-* Addition/Subtraction Operations
+/**
+* Two operand addition
+* @param x the first operand (and output)
+* @param x_size size of x
+* @param y the second operand
+* @param y_size size of y (must be >= x_size)
 */
 void bigint_add2(word x[], size_t x_size,
                  const word y[], size_t y_size);
 
+/**
+* Three operand addition
+*/
 void bigint_add3(word z[],
                  const word x[], size_t x_size,
                  const word y[], size_t y_size);
 
+/**
+* Two operand addition with carry out
+*/
 word bigint_add2_nc(word x[], size_t x_size, const word y[], size_t y_size);
 
+/**
+* Three operand addition with carry out
+*/
 word bigint_add3_nc(word z[],
                     const word x[], size_t x_size,
                     const word y[], size_t y_size);
 
+/**
+* Two operand subtraction
+*/
 word bigint_sub2(word x[], size_t x_size,
                  const word y[], size_t y_size);
 
 /**
-* x = y - x; assumes y >= x
+* Two operand subtraction, x = y - x; assumes y >= x
 */
 void bigint_sub2_rev(word x[], const word y[], size_t y_size);
 
+/**
+* Three operand subtraction
+*/
 word bigint_sub3(word z[],
                  const word x[], size_t x_size,
                  const word y[], size_t y_size);
diff --git a/src/tls/tls_alert.h b/src/tls/tls_alert.h
index b3001f259..f2c270704 100644
--- a/src/tls/tls_alert.h
+++ b/src/tls/tls_alert.h
@@ -1,6 +1,6 @@
 /*
 * Alert Message
-* (C) 2004-2006,2011 Jack Lloyd
+* (C) 2004-2006,2011,2012 Jack Lloyd
 *
 * Released under the terms of the Botan license
 */
@@ -21,6 +21,9 @@ namespace TLS {
 class BOTAN_DLL Alert
    {
    public:
+      /**
+      * Type codes for TLS alerts
+      */
       enum Type {
          CLOSE_NOTIFY                    = 0,
          UNEXPECTED_MESSAGE              = 10,
@@ -84,6 +87,11 @@ class BOTAN_DLL Alert
       */
       Alert(const std::vector<byte>& buf);
 
+      /**
+      * Create a new Alert
+      * @param alert_type the type of alert
+      * @param is_fatal specifies if this is a fatal alert
+      */
       Alert(Type alert_type, bool is_fatal = false) :
          fatal(is_fatal), type_code(alert_type) {}
 
diff --git a/src/tls/tls_ciphersuite.h b/src/tls/tls_ciphersuite.h
index 346c34f0b..74ad57991 100644
--- a/src/tls/tls_ciphersuite.h
+++ b/src/tls/tls_ciphersuite.h
@@ -1,6 +1,6 @@
 /*
 * TLS Cipher Suites
-* (C) 2004-2011 Jack Lloyd
+* (C) 2004-2011,2012 Jack Lloyd
 *
 * Released under the terms of the Botan license
 */
@@ -24,31 +24,74 @@ class BOTAN_DLL Ciphersuite
    public:
       /**
       * Convert an SSL/TLS ciphersuite to algorithm fields
+      * @param suite the ciphersuite code number
+      * @return ciphersuite object
       */
       static Ciphersuite by_id(u16bit suite);
 
+      /**
+      * Lookup a ciphersuite by name
+      * @param name the name (eg TLS_RSA_WITH_RC4_128_SHA)
+      * @return ciphersuite object
+      */
       static Ciphersuite by_name(const std::string& name);
 
+      /**
+      * Generate a static list of all known ciphersuites and return it.
+      *
+      * @return list of all known ciphersuites
+      */
       static const std::vector<Ciphersuite>& all_known_ciphersuites();
 
       /**
       * Formats the ciphersuite back to an RFC-style ciphersuite string
+      * @return RFC ciphersuite string identifier
       */
       std::string to_string() const;
 
+      /**
+      * @return ciphersuite number
+      */
       u16bit ciphersuite_code() const { return m_ciphersuite_code; }
 
+      /**
+      * @return true if this is a PSK ciphersuite
+      */
       bool psk_ciphersuite() const;
+
+      /**
+      * @return true if this is an ECC ciphersuite
+      */
       bool ecc_ciphersuite() const;
 
+      /**
+      * @return key exchange algorithm used by this ciphersuite
+      */
       std::string kex_algo() const { return m_kex_algo; }
+
+      /**
+      * @return signature algorithm used by this ciphersuite
+      */
       std::string sig_algo() const { return m_sig_algo; }
 
+      /**
+      * @return symmetric cipher algorithm used by this ciphersuite
+      */
       std::string cipher_algo() const { return m_cipher_algo; }
+
+      /**
+      * @return message authentication algorithm used by this ciphersuite
+      */
       std::string mac_algo() const { return m_mac_algo; }
 
+      /**
+      * @return cipher key length used by this ciphersuite
+      */
       size_t cipher_keylen() const { return m_cipher_keylen; }
 
+      /**
+      * @return true if this is a valid/known ciphersuite
+      */
       bool valid() const { return (m_cipher_keylen > 0); }
 
       Ciphersuite() : m_cipher_keylen(0) {}
diff --git a/src/tls/tls_extensions.h b/src/tls/tls_extensions.h
index 542ac0a82..60a375ebe 100644
--- a/src/tls/tls_extensions.h
+++ b/src/tls/tls_extensions.h
@@ -47,10 +47,19 @@ enum Handshake_Extension_Type {
 class Extension
    {
    public:
+      /**
+      * @return code number of the extension
+      */
       virtual Handshake_Extension_Type type() const = 0;
 
+      /**
+      * @return serialized binary for the extension
+      */
       virtual std::vector<byte> serialize() const = 0;
 
+      /**
+      * @return if we should encode this extension or not
+      */
       virtual bool empty() const = 0;
 
       virtual ~Extension() {}
@@ -211,6 +220,9 @@ class Next_Protocol_Notification : public Extension
       std::vector<std::string> m_protocols;
    };
 
+/**
+* Session Ticket Extension (RFC 5077)
+*/
 class Session_Ticket : public Extension
    {
    public:
@@ -219,6 +231,9 @@ class Session_Ticket : public Extension
 
       Handshake_Extension_Type type() const { return static_type(); }
 
+      /**
+      * @return contents of the session ticket
+      */
       const std::vector<byte>& contents() const { return m_ticket; }
 
       /**
diff --git a/src/tls/tls_heartbeats.h b/src/tls/tls_heartbeats.h
index f3cc9ec68..00b197089 100644
--- a/src/tls/tls_heartbeats.h
+++ b/src/tls/tls_heartbeats.h
@@ -14,6 +14,9 @@ namespace Botan {
 
 namespace TLS {
 
+/**
+* TLS Heartbeat message
+*/
 class Heartbeat_Message
    {
    public:
diff --git a/src/tls/tls_version.h b/src/tls/tls_version.h
index 38013445f..18d9f1674 100644
--- a/src/tls/tls_version.h
+++ b/src/tls/tls_version.h
@@ -15,6 +15,9 @@ namespace Botan {
 
 namespace TLS {
 
+/**
+* TLS Protocol Version
+*/
 class BOTAN_DLL Protocol_Version
    {
    public:
@@ -27,56 +30,87 @@ class BOTAN_DLL Protocol_Version
 
       Protocol_Version() : m_version(0) {}
 
+      /**
+      * @param named_version a specific named version of the protocol
+      */
       Protocol_Version(Version_Code named_version) :
          m_version(static_cast<u16bit>(named_version)) {}
 
+      /**
+      * @param major the major version
+      * @param minor the minor version
+      */
       Protocol_Version(byte major, byte minor) :
          m_version((static_cast<u16bit>(major) << 8) | minor) {}
 
+      /**
+      * @return true if this is a valid protocol version
+      */
       bool valid() const { return (m_version != 0); }
 
       /**
-      * Get the major version of the protocol version
+      * @return major version of the protocol version
       */
       byte major_version() const { return get_byte(0, m_version); }
 
       /**
-      * Get the minor version of the protocol version
+      * @return minor version of the protocol version
       */
       byte minor_version() const { return get_byte(1, m_version); }
 
+      /**
+      * @return human-readable description of this version
+      */
+      std::string to_string() const;
+
+      /**
+      * @return if this version is equal to other
+      */
       bool operator==(const Protocol_Version& other) const
          {
          return (m_version == other.m_version);
          }
 
+      /**
+      * @return if this version is not equal to other
+      */
       bool operator!=(const Protocol_Version& other) const
          {
          return (m_version != other.m_version);
          }
 
+      /**
+      * @return if this version is later than or equal to other
+      */
       bool operator>=(const Protocol_Version& other) const
          {
          return (m_version >= other.m_version);
          }
 
+      /**
+      * @return if this version is later than other
+      */
       bool operator>(const Protocol_Version& other) const
          {
          return (m_version > other.m_version);
          }
 
+      /**
+      * @return if this version is earlier than or equal to other
+      */
       bool operator<=(const Protocol_Version& other) const
          {
          return (m_version <= other.m_version);
          }
 
+      /**
+      * @return if this version is earlier than other
+      */
       bool operator<(const Protocol_Version& other) const
          {
          return (m_version < other.m_version);
          }
 
-      std::string to_string() const;
-
    private:
       u16bit m_version;
    };