1 files changed, 48 insertions, 2 deletions

diff --git a/src/entropy/entropy_src.h b/src/entropy/entropy_src.h
index 4d01bce7c..fa61d9ea8 100644
--- a/src/entropy/entropy_src.h
+++ b/src/entropy/entropy_src.h
@@ -1,4 +1,4 @@
-/**
+/*
 * EntropySource
 * (C) 2008-2009 Jack Lloyd
 *
@@ -20,23 +20,40 @@ namespace Botan {
 class BOTAN_DLL Entropy_Accumulator
    {
    public:
+      /**
+      * Initialize an Entropy_Accumulator
+      * @param goal is how many bits we would like to collect
+      */
       Entropy_Accumulator(u32bit goal) :
          entropy_goal(goal), collected_bits(0) {}
 
       virtual ~Entropy_Accumulator() {}
 
       /**
-      @return cached I/O buffer for repeated polls
+      * Get a cached I/O buffer (purely for minimizing allocation
+      * overhead to polls)
+      *
+      * @param size requested size for the I/O buffer
+      * @return cached I/O buffer for repeated polls
       */
       MemoryRegion<byte>& get_io_buffer(u32bit size)
          { io_buffer.resize(size); return io_buffer; }
 
+      /**
+      * @return number of bits collected so far
+      */
       u32bit bits_collected() const
          { return static_cast<u32bit>(collected_bits); }
 
+      /**
+      * @return if our polling goal has been achieved
+      */
       bool polling_goal_achieved() const
          { return (collected_bits >= entropy_goal); }
 
+      /**
+      * @return how many bits we need to reach our polling goal
+      */
       u32bit desired_remaining_bits() const
          {
          if(collected_bits >= entropy_goal)
@@ -44,12 +61,25 @@ class BOTAN_DLL Entropy_Accumulator
          return static_cast<u32bit>(entropy_goal - collected_bits);
          }
 
+      /**
+      * Add entropy to the accumulator
+      * @param bytes the input bytes
+      * @param length specifies how many bytes the input is
+      * @param entropy_bits_per_byte is a best guess at how much
+      * entropy per byte is in this input
+      */
       void add(const void* bytes, u32bit length, double entropy_bits_per_byte)
          {
          add_bytes(reinterpret_cast<const byte*>(bytes), length);
          collected_bits += entropy_bits_per_byte * length;
          }
 
+      /**
+      * Add entropy to the accumulator
+      * @param v is some value
+      * @param entropy_bits_per_byte is a best guess at how much
+      * entropy per byte is in this input
+      */
       template<typename T>
       void add(const T& v, double entropy_bits_per_byte)
          {
@@ -63,9 +93,16 @@ class BOTAN_DLL Entropy_Accumulator
       double collected_bits;
    };
 
+/**
+* Entropy accumulator that puts the input into a BufferedComputation
+*/
 class BOTAN_DLL Entropy_Accumulator_BufferedComputation : public Entropy_Accumulator
    {
    public:
+      /**
+      * @param sink the hash or MAC we are feeding the poll data into
+      * @param goal is how many bits we want to collect in this poll
+      */
       Entropy_Accumulator_BufferedComputation(BufferedComputation& sink,
                                               u32bit goal) :
          Entropy_Accumulator(goal), entropy_sink(sink) {}
@@ -85,8 +122,17 @@ class BOTAN_DLL Entropy_Accumulator_BufferedComputation : public Entropy_Accumul
 class BOTAN_DLL EntropySource
    {
    public:
+      /**
+      * @return name identifying this entropy source
+      */
       virtual std::string name() const = 0;
+
+      /**
+      * Perform an entropy gathering poll
+      * @param accum is an accumulator object that will be given entropy
+      */
       virtual void poll(Entropy_Accumulator& accum) = 0;
+
       virtual ~EntropySource() {}
    };