Issue #2598262: Typehint the entity as a facet, so IDE's are smarter about the subsequent calls to methods on the entity. Added more comments troughout the code.