Missing/incomplete documentation for reference properties

The documentation is sparse at best. It's missing entirely the option to use entities as values, and an example of retrieval of an entity which is then used as a value.

• Improved example in documentation
• Improved docstring