Since getDocumentObject() isn’t in the API quick reference, I always assumed that it was for internal use. I know better now.
A note on the $modx->documentObject variable (or a link to the modxcms page) might be really helpful on the API Quick Reference page. It’s a little hard to find, IMHO, until after you know about it. In fact, I just spent some time on the MODx Wiki and without searcing directly for it by name, I don’t think you’d find it and even in a direct name search, the API page is the 7th choice.
[update] I added the Wiki page to the API category and put a link on it to the modxcms.com page, which should help some. I also added a section on it to the snippet tips page.