[2369] Add API documentation for InputSource

src/lib/dns/inputsource.h

@@ -26,25 +26,47 @@ namespace isc {
 namespace dns {
 namespace master_lexer_internal {
 
+/// \brief An input source that is used internally by MasterLexer.
+///
+/// This is a helper internal class for MasterLexer, and represents
+/// state of a single source of the entire zone data to be
+/// parsed. Normally this means the master zone file, but MasterLexer
+/// can have multiple InputSources if $INCLUDE is used. The source can
+/// also be generic input stream (std::istream).
+///
+/// This class is not meant for public use.
 class InputSource {
 public:
+    /// \brief Constructor which takes an input stream. The stream is
+    /// read-from, but it is not closed.
     InputSource(std::istream& input_stream);
+
+    /// \brief Constructor which takes a filename to read from. The
+    /// associated file stream is managed internally.
     InputSource(const char* filename);
 
+    /// \brief Destructor
     ~InputSource();
 
+    /// \brief Returns a name for the InputSource. Typically this is the
+    /// filename, but if the InputSource was constructed for an
+    /// \c std::istream, it returns a name in the format "stream-%p".
     const std::string& getName() const {
         return (name_);
     }
 
+    /// \brief Returns if the input source is at end of file.
     bool atEOF() const {
         return (at_eof_);
     }
 
+    /// \brief Returns the current line number being read.
     size_t getCurrentLine() const {
         return (line_);
     }
 
+    /// \brief Saves the current line being read. Later, when
+    /// \c ungetAll() is called, it skips back to the last-saved line.
     void saveLine() {
         saved_line_ = line_;
     }
@@ -57,8 +79,17 @@ public:
         {}
     };
 
+    /// \brief Returns a single character from the input source. If end
+    /// of file is reached, -1 is returned.
     int getChar();
+
+    /// \brief Skips backward a single character in the input
+    /// source. The last-read character is unget.
     void ungetChar();
+
+    /// Forgets everything read so far, and skips back to the position
+    /// where reading started. If \c saveLine() was called previously,
+    /// it sets the current line number to the line number saved then.
     void ungetAll();
 
 private: