Improve rng doxygen [ci skip]

6 files changed, 82 insertions, 11 deletions

diff --git a/src/lib/rng/auto_rng/auto_rng.h b/src/lib/rng/auto_rng/auto_rng.h
index 6ef1aa291..9ae9b9c38 100644
--- a/src/lib/rng/auto_rng/auto_rng.h
+++ b/src/lib/rng/auto_rng/auto_rng.h
@@ -27,6 +27,9 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator
 
       bool is_seeded() const override;
 
+      /**
+      * Mark state as requiring a reseed on next use
+      */
       void force_reseed();
 
       size_t reseed(Entropy_Sources& srcs,
@@ -40,18 +43,44 @@ class BOTAN_DLL AutoSeeded_RNG final : public RandomNumberGenerator
       void clear() override;
 
       /**
-      * If no RNG or entropy sources are provided to AutoSeeded_RNG, it uses the system RNG
-      * (if available) or else a default group of entropy sources (all other systems) to
-      * gather seed material.
+      * Uses the system RNG (if available) or else a default group of
+      * entropy sources (all other systems) to gather seed material.
+      *
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
       */
       AutoSeeded_RNG(size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL);
 
+      /**
+      * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material.
+      *
+      * @param underlying_rng is a reference to some RNG which will be used
+      * to perform the periodic reseeding
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       AutoSeeded_RNG(RandomNumberGenerator& underlying_rng,
                      size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL);
 
+      /**
+      * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material.
+      *
+      * @param entropy_sources will be polled to perform reseeding periodically
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       AutoSeeded_RNG(Entropy_Sources& entropy_sources,
                      size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL);
 
+      /**
+      * Uses the BOTAN_AUTO_RNG_DRBG RNG to gather seed material.
+      *
+      * @param underlying_rng is a reference to some RNG which will be used
+      * to perform the periodic reseeding
+      * @param entropy_sources will be polled to perform reseeding periodically
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       AutoSeeded_RNG(RandomNumberGenerator& underlying_rng,
                      Entropy_Sources& entropy_sources,
                      size_t reseed_interval = BOTAN_RNG_DEFAULT_RESEED_INTERVAL);
diff --git a/src/lib/rng/hmac_drbg/hmac_drbg.h b/src/lib/rng/hmac_drbg/hmac_drbg.h
index 4f96af816..11d355d70 100644
--- a/src/lib/rng/hmac_drbg/hmac_drbg.h
+++ b/src/lib/rng/hmac_drbg/hmac_drbg.h
@@ -36,10 +36,14 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG
       /**
       * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
       *
+      * Automatic reseeding from @p underlying_rng will take place after
+      * @p reseed_interval many requests or after a fork was detected.
+      *
+      * @param prf MAC to use as a PRF
       * @param underlying_rng is a reference to some RNG which will be used
       * to perform the periodic reseeding
       * @param reseed_interval specifies a limit of how many times
-      * the RNG will be called before automatic reseeding is performed.
+      * the RNG will be called before automatic reseeding is performed
       */
       HMAC_DRBG(std::unique_ptr<MessageAuthenticationCode> prf,
                 RandomNumberGenerator& underlying_rng,
@@ -48,6 +52,10 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG
       /**
       * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
       *
+      * Automatic reseeding from @p entropy_sources will take place after
+      * @p reseed_interval many requests or after a fork was detected.
+      *
+      * @param prf MAC to use as a PRF
       * @param entropy_sources will be polled to perform reseeding periodically
       * @param reseed_interval specifies a limit of how many times
       * the RNG will be called before automatic reseeding is performed.
@@ -59,6 +67,11 @@ class BOTAN_DLL HMAC_DRBG final : public Stateful_RNG
       /**
       * Initialize an HMAC_DRBG instance with the given MAC as PRF (normally HMAC)
       *
+      * Automatic reseeding from @p underlying_rng and @p entropy_sources
+      * will take place after @p reseed_interval many requests or after
+      * a fork was detected.
+      *
+      * @param prf MAC to use as a PRF
       * @param underlying_rng is a reference to some RNG which will be used
       * to perform the periodic reseeding
       * @param entropy_sources will be polled to perform reseeding periodically
diff --git a/src/lib/rng/rdrand_rng/rdrand_rng.h b/src/lib/rng/rdrand_rng/rdrand_rng.h
index fcd54035b..94363b89c 100644
--- a/src/lib/rng/rdrand_rng/rdrand_rng.h
+++ b/src/lib/rng/rdrand_rng/rdrand_rng.h
@@ -45,6 +45,9 @@ class BOTAN_DLL RDRAND_RNG : public Hardware_RNG
       void add_entropy(const uint8_t[], size_t) override
          { /* no op */ }
 
+      /*
+      * No way to reseed RDRAND generator, so reseed is ignored
+      */
       size_t reseed(Entropy_Sources&, size_t, std::chrono::milliseconds) override
          { return 0; /* no op */ }
 
diff --git a/src/lib/rng/rng.h b/src/lib/rng/rng.h
index e3640a32f..36a423eca 100644
--- a/src/lib/rng/rng.h
+++ b/src/lib/rng/rng.h
@@ -38,7 +38,7 @@ class BOTAN_DLL RandomNumberGenerator
       /**
       * Randomize a byte array.
       * @param output the byte array to hold the random output.
-      * @param length the length of the byte array output.
+      * @param length the length of the byte array output in bytes.
       */
       virtual void randomize(byte output[], size_t length) = 0;
 
@@ -70,7 +70,12 @@ class BOTAN_DLL RandomNumberGenerator
       * Use this to further bind the outputs to your current
       * process/protocol state. For instance if generating a new key
       * for use in a session, include a session ID or other such
-      * value.  See NIST SP 800-90 A, B, C series for more ideas.
+      * value. See NIST SP 800-90 A, B, C series for more ideas.
+      *
+      * @param output buffer to hold the random output
+      * @param output_len size of the output buffer in bytes
+      * @param input entropy buffer to incorporate
+      * @param input_len size of the input buffer in bytes
       */
       virtual void randomize_with_input(byte output[], size_t output_len,
                                         const byte input[], size_t input_len);
@@ -78,8 +83,8 @@ class BOTAN_DLL RandomNumberGenerator
       /**
       * This calls `randomize_with_input` using some timestamps as extra input.
       *
-      * For a stateful RNG using non-random but potentially unique data as the
-      * additional_input can help protect against problems with fork, VM state
+      * For a stateful RNG using non-random but potentially unique data the
+      * extra input can help protect against problems with fork, VM state
       * rollback, or other cases where somehow an RNG state is duplicated. If
       * both of the duplicated RNG states later incorporate a timestamp (and the
       * timestamps don't themselves repeat), their outputs will diverge.
@@ -87,7 +92,7 @@ class BOTAN_DLL RandomNumberGenerator
       virtual void randomize_with_ts_input(byte output[], size_t output_len);
 
       /**
-      * Return the name of this RNG type
+      * @return the name of this RNG type
       */
       virtual std::string name() const = 0;
 
@@ -143,6 +148,9 @@ class BOTAN_DLL RandomNumberGenerator
          return b;
          }
 
+      /**
+      * @return a random byte that is not the zero byte
+      */
       byte next_nonzero_byte()
          {
          byte b = this->next_byte();
diff --git a/src/lib/rng/stateful_rng/stateful_rng.h b/src/lib/rng/stateful_rng/stateful_rng.h
index 11f0c7e3d..4eed85d0d 100644
--- a/src/lib/rng/stateful_rng/stateful_rng.h
+++ b/src/lib/rng/stateful_rng/stateful_rng.h
@@ -25,6 +25,13 @@ namespace Botan {
 class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator
    {
    public:
+      /**
+      * @param rng is a reference to some RNG which will be used
+      * to perform the periodic reseeding
+      * @param entropy_sources will be polled to perform reseeding periodically
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       Stateful_RNG(RandomNumberGenerator& rng,
                    Entropy_Sources& entropy_sources,
                    size_t reseed_interval) :
@@ -33,11 +40,22 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator
          m_reseed_interval(reseed_interval)
          {}
 
+      /**
+      * @param underlying_rng is a reference to some RNG which will be used
+      * to perform the periodic reseeding
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       Stateful_RNG(RandomNumberGenerator& rng, size_t reseed_interval) :
          m_underlying_rng(&rng),
          m_reseed_interval(reseed_interval)
          {}
 
+      /**
+      * @param entropy_sources will be polled to perform reseeding periodically
+      * @param reseed_interval specifies a limit of how many times
+      * the RNG will be called before automatic reseeding is performed
+      */
       Stateful_RNG(Entropy_Sources& entropy_sources, size_t reseed_interval) :
          m_entropy_sources(&entropy_sources),
          m_reseed_interval(reseed_interval)
@@ -81,7 +99,7 @@ class BOTAN_DLL Stateful_RNG : public RandomNumberGenerator
                     std::chrono::milliseconds poll_timeout = BOTAN_RNG_RESEED_DEFAULT_TIMEOUT) override;
 
       /**
-      * Return intended security level of this DRBG
+      * @return intended security level of this DRBG
       */
       virtual size_t security_level() const = 0;
 
diff --git a/src/lib/rng/system_rng/system_rng.h b/src/lib/rng/system_rng/system_rng.h
index 9cf31e78b..a31bb1dba 100644
--- a/src/lib/rng/system_rng/system_rng.h
+++ b/src/lib/rng/system_rng/system_rng.h
@@ -20,7 +20,7 @@ namespace Botan {
 BOTAN_DLL RandomNumberGenerator& system_rng();
 
 /*
-* Instantiatable reference to the system RNG.
+* Instantiable reference to the system RNG.
 */
 class BOTAN_DLL System_RNG final : public RandomNumberGenerator
    {