Units: doxy explanation

Base/Const/Units.h

@@ -16,11 +16,21 @@
 #define BORNAGAIN_BASE_CONST_UNITS_H
 
 //! Constants and functions for physical unit conversions.
+//!
+//! In user code, quantities that have a physical dimension should always
+//! be given in the form _value * unit_, e.g. 0.529 * angstrom for a length,
+//! or 45 * deg for an angle.
+//!
+//! Internally, BornAgain has length, angle, magnetic field units of nanometer,
+//! radians, Tesla. Therefore, in principle, the multipliers nm, rad, tesla could
+//! be ommited from code. However, to make code more readable, and to prevent
+//! misunderstandings, we recommend that physical dimension be always made clear
+//! by multiplying values with an appropriate constant, even if this expands to 1.
 
 namespace Units {
 
 // Length
-static constexpr double nanometer = 1.;
+static constexpr double nanometer = 1.; //!< Internal unit for lengths
 static constexpr double angstrom = 1.e-1 * nanometer;
 static constexpr double micrometer = 1.e+3 * nanometer;
 static constexpr double millimeter = 1.e+6 * nanometer;
@@ -32,11 +42,11 @@ static constexpr double nm = nanometer;
 static constexpr double nm2 = nanometer * nanometer;
 
 // Angle
-static constexpr double rad = 1.;
+static constexpr double rad = 1.; //!< Radian, internal unit for angles
 static constexpr double deg = (3.1415926535897932 / 180.0) * rad;
 
 // Magnetic field
-static constexpr double tesla = 1.;
+static constexpr double tesla = 1.; //!< Internal unit for magnetic fields
 static constexpr double gauss = 1e-4;
 
 // Converters