diff --git a/doc/doxygen/Doxylocal b/doc/doxygen/Doxylocal
index db859f51a..da261f76f 100644
--- a/doc/doxygen/Doxylocal
+++ b/doc/doxygen/Doxylocal
@@ -9,7 +9,8 @@
 INPUT                 += @abs_top_srcdir@/opm/
 
 # see e.g. dune-grid for the examples of mainpage and modules
-# INPUT                 += @abs_top_srcdir@/doc/doxygen/mainpage #                          @srcdir@/modules
+# INPUT                 += @abs_top_srcdir@/doc/doxygen/mainpage
+#                          @srcdir@/modules
 
 # The EXCLUDE tag can be used to specify files and/or directories that should
 # excluded from the INPUT source files. This way you can easily exclude a
diff --git a/examples/sim_2p_comp_ad.cpp b/examples/sim_2p_comp_ad.cpp
index a511d5d95..8a06df3ca 100644
--- a/examples/sim_2p_comp_ad.cpp
+++ b/examples/sim_2p_comp_ad.cpp
@@ -155,7 +155,7 @@ try
         simple_wells = create_wells(2, 2, 2);
         const double inj_frac[2] = { 1.0, 0.0 };
         const int inj_cell = 0;
-        const double WI = 1e-8;
+        const double WI = 1e-8; // This is a completely made-up number.
         const double all_fluids[2] = { 1.0, 1.0 };
         int ok = add_well(INJECTOR, 0.0, 1, inj_frac, &inj_cell, &WI, "Injector", simple_wells);
         ok = ok && append_well_controls(SURFACE_RATE, 0.01*flow_per_sec, all_fluids, 0, simple_wells);
diff --git a/opm/autodiff/AutoDiffBlock.hpp b/opm/autodiff/AutoDiffBlock.hpp
index 56fbfd451..b10cbfdc6 100644
--- a/opm/autodiff/AutoDiffBlock.hpp
+++ b/opm/autodiff/AutoDiffBlock.hpp
@@ -32,15 +32,15 @@ namespace Opm
     /// values and sparse jacobian matrices.
     ///
     /// The class contains a (column) vector of values and multiple
-    /// sparse matrices representing its derivatives. Each such matrix
-    /// has a number of rows equal to the number of rows in the value
-    /// vector, and a number of columns equal to the number of
-    /// variables we want to compute the derivatives with respect
-    /// to. The reason to have multiple such jacobians instead of just
-    /// one is to allow simpler grouping of variables, making it
-    /// easier to implement various preconditioning schemes. Only
-    /// basic arithmetic operators are implemented for this class,
-    /// reflecting our needs so far.
+    /// sparse matrices representing its partial derivatives. Each
+    /// such matrix has a number of rows equal to the number of rows
+    /// in the value vector, and a number of columns equal to the
+    /// number of discrete variables we want to compute the
+    /// derivatives with respect to. The reason to have multiple such
+    /// jacobians instead of just one is to allow simpler grouping of
+    /// variables, making it easier to implement various
+    /// preconditioning schemes. Only basic arithmetic operators are
+    /// implemented for this class, reflecting our needs so far.
     ///
     /// The class is built on the Eigen library, using an Eigen array
     /// type to contain the values and Eigen sparse matrices for the
diff --git a/opm/autodiff/AutoDiffHelpers.hpp b/opm/autodiff/AutoDiffHelpers.hpp
index 8959c2c79..66472b83b 100644
--- a/opm/autodiff/AutoDiffHelpers.hpp
+++ b/opm/autodiff/AutoDiffHelpers.hpp
@@ -42,15 +42,15 @@ struct HelperOps
     typedef Eigen::Array<int, Eigen::Dynamic, 1> IFaces;
     IFaces internal_faces;
 
-    /// Extract for each internal face the difference of its adjacent cells'values (first - second).
+    /// Extract for each internal face the difference of its adjacent cells' values (first - second).
     M ngrad;
-    /// Extract for each face the difference of its adjacent cells'values (second - first).
+    /// Extract for each face the difference of its adjacent cells' values (second - first).
     M grad;
     /// Extract for each face the average of its adjacent cells' values.
     M caver;
     /// Extract for each cell the sum of its adjacent interior faces' (signed) values.
     M div;
-    /// Extract for each face the difference of its adjacent cells'values (first - second).
+    /// Extract for each face the difference of its adjacent cells' values (first - second).
     /// For boundary faces, one of the entries per row (corresponding to the outside) is zero.
     M fullngrad;
     /// Extract for each cell the sum of all its adjacent faces' (signed) values.
diff --git a/opm/autodiff/BlackoilPropsAd.hpp b/opm/autodiff/BlackoilPropsAd.hpp
index b00a00f29..70545d4f6 100644
--- a/opm/autodiff/BlackoilPropsAd.hpp
+++ b/opm/autodiff/BlackoilPropsAd.hpp
@@ -34,12 +34,11 @@ namespace Opm
     ///
     /// It is implemented by wrapping a BlackoilPropertiesInterface
     /// object (the interface class defined in opm-core) and calling
-    /// its methods. This approach works well for most methods, but
-    /// the rsMax() method cannot be implemented by such a wrapping,
-    /// without access to the underlying pvt objects. Therefore we
-    /// cannot use this class with any case that involves
-    /// miscibility. A rethinking of fluid interfaces is probably
-    /// necessary.
+    /// its methods. This class does not implement rsMax() because the
+    /// required information is not available when wrapping a
+    /// BlackoilPropertiesInterface. Consequently, class
+    /// BlackoilPropsAd cannot be used to simulate problems involving
+    /// miscibility.
     ///
     /// Most methods are available in two overloaded versions, one
     /// taking a constant vector and returning the same, and one
diff --git a/opm/autodiff/GeoProps.hpp b/opm/autodiff/GeoProps.hpp
index 2b321c1c5..fbf646295 100644
--- a/opm/autodiff/GeoProps.hpp
+++ b/opm/autodiff/GeoProps.hpp
@@ -27,7 +27,7 @@
 namespace Opm
 {
 
-    /// Class containing static geological properties that can be
+    /// Class containing static geological properties that are
     /// derived from grid and petrophysical properties:
     ///   - pore volume
     ///   - transmissibilities