improved documentation

this is a leftover bit straggling behind the other PR about associated models. Just a few sentences of improved inline documentation.