provide meaningful docstrings in Python API

Long-standing request by ESS. See comparison with other software in the attached PDF. ba_vs_refnx_refl1d.pdf