BIND 10 trac2371, updated. f5c629c8fa3da5089a4260187901b2d36799a2f2 [2371] added notes about the two mode of error handling: retval and exception.

[BIND 10 source code commits]

The branch, trac2371 has been updated
       via  f5c629c8fa3da5089a4260187901b2d36799a2f2 (commit)
       via  c1e1248555eddb771d776fe614d3078d7dfab26c (commit)
      from  282cb2ff2eb38f9ad46653c55d0d2974ca1df541 (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 f5c629c8fa3da5089a4260187901b2d36799a2f2
Author: JINMEI Tatuya <jinmei at isc.org>
Date:   Mon Nov 5 09:32:42 2012 -0800

    [2371] added notes about the two mode of error handling: retval and exception.

commit c1e1248555eddb771d776fe614d3078d7dfab26c
Author: JINMEI Tatuya <jinmei at isc.org>
Date:   Mon Nov 5 08:58:31 2012 -0800

    [2371] cleanup: removed now-unnecessary include

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

Summary of changes:
 src/lib/dns/master_lexer.cc |    1 -
 src/lib/dns/master_lexer.h  |   26 ++++++++++++++++++++++++++
 2 files changed, 26 insertions(+), 1 deletion(-)

-----------------------------------------------------------------------
diff --git a/src/lib/dns/master_lexer.cc b/src/lib/dns/master_lexer.cc
index 6197a9c..c9c5528 100644
--- a/src/lib/dns/master_lexer.cc
+++ b/src/lib/dns/master_lexer.cc
@@ -21,7 +21,6 @@
 
 #include <cassert>
 #include <string>
-#include <sstream>
 #include <vector>
 
 namespace isc {
diff --git a/src/lib/dns/master_lexer.h b/src/lib/dns/master_lexer.h
index c671ef7..da6bb5d 100644
--- a/src/lib/dns/master_lexer.h
+++ b/src/lib/dns/master_lexer.h
@@ -42,6 +42,27 @@ namespace dns {
 /// applications; it's mainly expected to be used within this library,
 /// specifically by the \c MasterLoader class and \c Rdata implementation
 /// classes.
+///
+/// \note The error handling policy of this class is slightly different from
+/// that of other classes of this library.  We generally throw an exception
+/// for an invalid input, whether it's more likely to be a program error or
+/// a "user error", which means an invalid input that comes from outside of
+/// the library.  But, this class returns an error code for some certain
+/// types of user errors instead of throwing an exception.  Such cases include
+/// a syntax error identified by the lexer or a misspelled file name that
+/// causes a system error at the time of open.  This is based on the assumption
+/// that the main user of this class is a parser of master files, where
+/// we want to give an option to ignore some non fatal errors and continue
+/// the parsing.  This will be useful if it just performs overall error
+/// checks on a master file.  When the (immediate) caller needs to do explicit
+/// error handling, exceptions are not that a useful tool for error reporting
+/// because we cannot separate the normal and error cases anyway, which would
+/// be one major advantage when we use exceptions.  And, exceptions are
+/// generally more expensive, either when it happens or just by being able
+/// to handle with \c try and \c catch (depending on the underlying
+/// implementation of the exception handling).  For these reasons, some of
+/// this class does not throw for an error that would be reported as an
+/// exception in other classes.
 class MasterLexer {
 public:
     class Token;       // we define it separately for better readability
@@ -69,6 +90,11 @@ public:
     /// will be discarded).  If opening the file succeeds, the given
     /// \c error parameter will be intact.
     ///
+    /// Note that this method has two styles of error reporting: one by
+    /// returning \c false (and setting \c error optionally) and the other
+    /// by throwing an exception.  See the note for the class description
+    /// about the distinction.
+    ///
     /// \throw InvalidParameter filename is NULL
     /// \param filename A non NULL string specifying a master file
     /// \param error If non null, a placeholder to set error description in