Adds some documentation to OpmInputError.hpp.

opm/common/utility/OpmInputError.hpp

@@ -60,8 +60,13 @@ public:
         {file} -> loc.filename
         {line} -> loc.lineno
 
+      additionally, the message can contain any number of named or positional
+      arguments to add further context to the message.
+
       KeywordLocation loc("KW", "file.inc", 100);
-      OpmInputError("Error at line {line} in file{file} - keyword: {keyword} ignored", location)
+      OpmInputError("Error at line {line} in file {file} - keyword: {keyword} ignored", location);
+      OpmInputError("Error at line {line} in file {file} - keyword: {keyword} has invalid argument {}", invalid_argument);
+      OpmInputError("Error at line {line} in file {file} - keyword: {keyword} has invalid argument {argument}", fmt::arg("argument", invalid_argument));
     */
 
     template<class ... Args>
@@ -70,6 +75,21 @@ public:
         location { loc }
     {}
 
+    /*
+      Allows for the initialisation of an OpmInputError from another exception.
+
+      Usage:
+
+      try {
+          .
+          .
+          .
+      } catch (const Opm::OpmInputError&) {
+          throw;
+      } catch (const std::exception& e) {
+          std::throw_with_nested(Opm::OpmInputError(location, e));
+      }
+    */
     OpmInputError(const KeywordLocation& loc, const std::exception& e, const std::string& reason = "Internal error message") :
         m_what   { OpmInputError::formatException(loc, e, reason) },
         location { loc }

tests/test_OpmInputError_format.cpp

@@ -22,6 +22,8 @@
 
 #include <boost/test/unit_test.hpp>
 
+#include <exception>
+
 #include <opm/common/utility/OpmInputError.hpp>
 
 const Opm::KeywordLocation location { "MXUNSUPP", "FILENAME.DAT", 42 } ;
@@ -83,3 +85,19 @@ Reason: Runtime Error)" };
 
     BOOST_CHECK_EQUAL(formatted, expected);
 }
+
+BOOST_AUTO_TEST_CASE(exception_nest) {
+    const std::string expected { R"(Problem parsing keyword MXUNSUPP
+In FILENAME.DAT line 42.
+Internal error message: Runtime Error)" };
+
+    try {
+        try {
+            throw std::runtime_error("Runtime Error");
+        } catch (const std::exception& e) {
+            std::throw_with_nested(Opm::OpmInputError(location, e));
+        }
+    } catch (const Opm::OpmInputError& opm_error) {
+        BOOST_CHECK_EQUAL(opm_error.what(), expected);
+    }
+}