BIND 10 trac2377, updated. 5ec0945ea8abd8ce3aa59aa851421269d9f807d4 [2377] Documentation for MasterLoader

[BIND 10 source code commits]

The branch, trac2377 has been updated
       via  5ec0945ea8abd8ce3aa59aa851421269d9f807d4 (commit)
      from  11ed5b5ca1fb48c7754c1d85b65fa00b00630d78 (commit)

Those revisions listed above that are new to this repository have
not appeared on any other notification email; so we list those
revisions in full, below.

- Log -----------------------------------------------------------------
commit 5ec0945ea8abd8ce3aa59aa851421269d9f807d4
Author: Michal 'vorner' Vaner <michal.vaner at nic.cz>
Date:   Tue Dec 4 12:09:36 2012 +0100

    [2377] Documentation for MasterLoader

-----------------------------------------------------------------------

Summary of changes:
 src/lib/dns/master_loader.h |   60 ++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 56 insertions(+), 4 deletions(-)

-----------------------------------------------------------------------
diff --git a/src/lib/dns/master_loader.h b/src/lib/dns/master_loader.h
index dbc3d96..3079bf8 100644
--- a/src/lib/dns/master_loader.h
+++ b/src/lib/dns/master_loader.h
@@ -17,29 +17,81 @@
 
 #include <dns/master_loader_callbacks.h>
 
+#include <boost/noncopyable.hpp>
+
 namespace isc {
 namespace dns {
 
 class Name;
 class RRClass;
 
-class MasterLoader {
+/// \brief A class able to load DNS master files
+///
+/// This class is able to produce a stream of RRs from a master file.
+/// It is able to load all of the master file at once, or by blocks
+/// incrementally.
+///
+/// It reports the loaded RRs and encountered errors by callbacks.
+class MasterLoader : boost::noncopyable {
 public:
+    /// \brief Options how the parsing should work.
     enum Options {
-        DEFAULT = 0,
-        MANY_ERRORS        ///< Lenient mode
+        DEFAULT = 0,       ///< Nothing special.
+        MANY_ERRORS = 1    ///< Lenient mode.
     };
+    /// \brief Constructor
+    ///
+    /// This creates a master loader and provides it with all
+    /// relevant information.
+    ///
+    /// Except for the exceptions listed below, the constructor doesn't
+    /// throw. Most errors (like non-existent master file) are reported
+    /// by the callbacks during load() or loadIncremental().
+    ///
+    /// \param master_file Path to the file to load.
+    /// \param zone_origin The origin of zone to be expected inside
+    ///     the master file. Currently unused, but it is expected to
+    ///     be used for some validation.
+    /// \param zone_class The class of zone to be expected inside the
+    ///     master file.
+    /// \param callbacks The callbacks by which it should report problems.
+    /// \param add_callback The callback which would be called with each
+    ///     loaded RR.
+    /// \param options Options for the parsing, which is bitwise-or of
+    ///     the Options values or DEFAULT. If the MANY_ERRORS option is
+    ///     included, the parser tries to continue past errors. If it
+    ///     is not included, it stops at first encountered error.
+    /// \throw std::bad_alloc when there's not enough memory.
+    /// \throw isc::InvalidParameter if add_callback is empty.
     MasterLoader(const char* master_file,
                  const Name& zone_origin,
                  const RRClass& zone_class,
                  const MasterLoaderCallbacks& callbacks,
                  const AddRRCallback& add_callback,
                  Options options = DEFAULT);
+    /// \brief Destructor
     ~MasterLoader();
 
+    /// \brief Load some RRs
+    ///
+    /// This method loads at most count_limit RRs and reports them. In case
+    /// an error (either fatal or without MANY_ERRORS) or end of file is
+    /// encountered, they may be less.
+    ///
+    /// \param count_limit Upper limit on the number of RRs loaded.
+    /// \return In case it stops because of the count limit, it returns false.
+    ///     It returns true if the loading is done.
+    /// \throw isc::InvalidOperation when called after loading was done
+    ///     already.
     bool loadIncremental(size_t count_limit);
+    /// \brief Load everything
+    ///
+    /// This simply calls loadIncremental until the loading is done.
+    /// \throw isc::InvalidOperation when called after loading was done
+    ///     already.
     void load() {
-        while (!loadIncremental(1000)) {
+        while (!loadIncremental(1000)) { // 1000 = arbitrary largish number
+            // Body intentionally left blank
         }
     }