Added some comments and documentation

opm/parser/eclipse/Logger.cpp

@@ -23,6 +23,8 @@ using namespace boost::posix_time;
 #include "Logger.hpp"
 
 namespace Opm {
+  
+  /// The log levels, used to avoid clutter in the log
   const int Logger::DEBUG = 0;
   const int Logger::INFO = 1;
   const int Logger::ERROR = 2;
@@ -35,23 +37,26 @@ namespace Opm {
     m_logLevel = logLevel;
   }
 
+  /// Changes the default path from log.log to path
   void Logger::setPath(const std::string& path) {
     m_logFile = path;
   }
 
+  /// Logs a debug message
   void Logger::debug(const std::string& message) {
-
     if (m_logLevel <= DEBUG) {
       log(message, "DEBUG");
     }
   }
 
+  /// Logs an info message
   void Logger::info(const std::string& message) {
     if (m_logLevel <= INFO) {
       log(message, "INFO");
     }
   }
 
+  /// Logs an error message
   void Logger::error(const std::string& message) {
     if (m_logLevel <= ERROR) {
       log(message, "ERROR");

opm/parser/eclipse/Logger.hpp

@@ -25,6 +25,9 @@
 
 namespace Opm {
 
+  /// Class to use for simple logging to file. Default output file is log.log
+  /// initLogger and closeLogger have to be called to open and close the stream.
+  /// The logging is performed using the debug, info and error methods.
   class Logger {
   public:
     static const int DEBUG;

opm/parser/eclipse/Parser/Parser.hpp

@@ -29,12 +29,18 @@
 
 namespace Opm {
 
+  /// The hub of the parsing process.
+  /// An input file in the eclipse data format is specified, several steps of parsing is performed
+  /// and the semantically parsed result is returned.
   class Parser {
   public:
     Parser();
+
+    /// The starting point of the parsing process. The supplied file is parsed, and the resulting Deck is returned.
     RawDeckPtr parse(const std::string &path);
     virtual ~Parser();
-
+    
+    /// Method to add ParserKW instances, these holding type and size information about the keywords and their data.
     void addKW(ParserKWConstPtr parserKW);
 
   private:

opm/parser/eclipse/RawDeck/RawConsts.hpp

@@ -22,6 +22,8 @@
 
 
 namespace Opm {
+
+  /// Consts used in the non semantic, raw parsing of the eclipse file
   namespace RawConsts {
     const char slash = '/';
     const char quote = '\'';

opm/parser/eclipse/RawDeck/RawDeck.cpp

@@ -28,11 +28,9 @@ namespace Opm {
     m_rawParserKWs = rawParserKWs;
   }
 
-  /*
-   * Iterate through list of RawKeywords in search for the specified string.
-   * O(n), not using map or hash because the keywords are not unique, 
-   * and the order matters. Returns first matching keyword.
-   */
+  /// Iterate through list of RawKeywords in search for the specified string.
+  /// O(n), not using map or hash because the keywords are not unique, 
+  /// and the order matters. Returns first matching keyword.
   RawKeywordConstPtr RawDeck::getKeyword(const std::string& keyword) const {
     for (std::list<RawKeywordConstPtr>::const_iterator it = m_keywords.begin(); it != m_keywords.end(); it++) {
       if ((*it)->getKeyword() == keyword) {
@@ -51,6 +49,10 @@ namespace Opm {
     return false;
   }
 
+  /// The main data reading function, reads one and one keyword into the RawDeck
+  /// If the INCLUDE keyword is found, the specified include file is inline read into the RawDeck.
+  /// The data is read into a keyword, record by record, until the fixed number of records specified
+  /// in the RawParserKW is met, or till a slash on a separate line is found.
   void RawDeck::readDataIntoDeck(const std::string& path) {
     boost::filesystem::path dataFolderPath = verifyValidInputPath(path);
     {
@@ -116,6 +118,8 @@ namespace Opm {
     return m_keywords.size();
   }
 
+  /// Checks if the current keyword being read is finished, based on the number of records
+  /// specified for the current keyword type in the RawParserKW class.
   bool RawDeck::isKeywordFinished(RawKeywordConstPtr rawKeyword) {
     if (m_rawParserKWs->keywordExists(rawKeyword->getKeyword())) {
       return rawKeyword->getNumberOfRecords() == m_rawParserKWs->getFixedNumberOfRecords(rawKeyword->getKeyword());
@@ -123,6 +127,7 @@ namespace Opm {
     return false;
   }
 
+  /// Operator overload to write the content of the RawDeck to an ostream
   std::ostream& operator<<(std::ostream& os, const RawDeck& deck) {
     for (std::list<RawKeywordConstPtr>::const_iterator keyword = deck.m_keywords.begin(); keyword != deck.m_keywords.end(); keyword++) {
       os << (*keyword)->getKeyword() << "                -- Keyword\n";

opm/parser/eclipse/RawDeck/RawDeck.hpp

@@ -30,9 +30,19 @@
 
 namespace Opm {
 
+  /// Class representing the most high level structure, a deck. The RawDeck holds non parsed
+  /// data, in the form of a list of RawKeywords. The order of the keywords is important, as this
+  /// reflects the order they were read in from the eclipse file. The RawDeck forms the basis of the 
+  /// semantic parsing that comes after the RawDeck has been created from the eclipse file.
   class RawDeck {
   public:
+
+    /// Constructor that requires information about the fixed record length keywords. 
+    /// All relevant keywords with a fixed number of records 
+    /// must be specified through the RawParserKW class. This is to be able to know how the records
+    /// of the keyword is structured.
     RawDeck(RawParserKWsConstPtr rawParserKWs);
+    
     RawKeywordConstPtr getKeyword(const std::string& keyword) const;
     bool hasKeyword(const std::string& keyword) const;
     void readDataIntoDeck(const std::string& path);

opm/parser/eclipse/RawDeck/RawKeyword.cpp

@@ -94,7 +94,8 @@ namespace Opm {
       throw std::invalid_argument("Illegal whitespace start of keyword:" + keyword);
     }
   }
-
+  /// Important method, being repeatedly called. When a record is terminated,
+  /// it is added to the list of records, and a new record is started.
   void RawKeyword::addRawRecordString(const std::string& partialRecordString) {
     m_partialRecordString += partialRecordString;
     if (RawRecord::isTerminatedRecordString(partialRecordString)) {

opm/parser/eclipse/RawDeck/RawKeyword.hpp

@@ -30,6 +30,10 @@
 
 namespace Opm {
 
+    /// Class representing a RawKeyword, meaning both the actual keyword phrase, and the records,
+    /// represented as a list of RawRecord objects.
+    /// The class also contains static functions to aid the parsing of the input file.
+    /// The creationg of an instance is performed by calling the addRawRecordString method repeatedly.
     class RawKeyword {
     public:
         RawKeyword();

opm/parser/eclipse/RawDeck/RawParserKWs.hpp

@@ -13,6 +13,9 @@
 #include <boost/shared_ptr.hpp>
 namespace Opm {
 
+  /// Class holding information about the characteristics of all known fixed length keywords.
+  /// The characteristics being held is the ones important for the raw parsing,
+  /// these being the keywords name and fixed number of records for the keyword.
   class RawParserKWs {
   public:
     RawParserKWs();

opm/parser/eclipse/RawDeck/RawRecord.hpp

@@ -26,6 +26,9 @@
 
 namespace Opm {
 
+  /// Class representing the lowest level of the Raw datatypes, a record. A record is simply
+  /// a vector containing the record elements, represented as strings. Some logic is present
+  /// to handle special elements in a record string, particularly with quote characters.
   class RawRecord {
   public:
     RawRecord();