Added a section to document the attributes.
(fix) clarify noted areas in docs

[skip ci]
(maint) small formatting tweaks
Merge branch 'ross-williams-patch-1'