Documentation tweaks

Taking on board @lsegals feedback, I've also normalised all of our `@param` calls to be `@param [Type] value "readable message"`