Fix all docstrings

[kerimoyle]

Just a general note that I've noticed a function description that's not quite true, and there are probably others ...
(a UnitsPtr is not the name, it's the pointer ...)

    /**
     * @brief Get the name of the units for this variable.
     *
     * Get the name of the units for this variable. If no units are set
     * an empty @c std::string is returned.
     *
     * @sa setUnits
     * @sa removeUnits
     *
     * @return The @c UnitsPtr of the units for this variable.
     */
    UnitsPtr units() const;

[kerimoyle]

We also need to make a schema for docstrings and follow it:

• when referencing a parameter, we use the @p prefix and the actual variable name (not the description of the parameter)?
• when referencing an object that has a pointer, do we use the pointer type or the pointed-to type? ie: when passing a model to the printer, should it be discussed as a @c ModelPtr or a @c Model or just a model?
• when just talking about the conceptual thing rather than the code-representation, should we be using any kind of markup at all?
• how do we talk about null pointers?
• how do we talk about the range of vectors?