Follow patterns
Move init to top of class
Change asserts to more meaningful exception types
Refactor hard-to-read fn
Change DescriptionLocator to DefinitionLocator
Merge pull request #1137 from edx/dhm/pr271_fixups

old pr 271 comment fixups