Developers should get a information that Element.empty fires only dispose (against my first guess of destroy) on all children. Maybe a advise like Call myElement.getChildren().destroy() to prepare all items for garbage collection should help, too.
Call myElement.getChildren().destroy() to prepare all items for garbage collection
I didn't know it before I have took a look into the code and have now some troubles resulting out this.
Also possible: since nobody should know it without looking in the code, I would recommend to call destroy instead of dispose like @kentaromiura it did in his pull request #2351 (4c68d39) to prevent a memory leak. But the hint mentioned above should also do it.
in all fairness, yes, http://mootools.net/docs/core/Element/Element#Element:empty is probably a bit vague. as a whole, it would be awesome if methods could be linked to a line on github where the source can be seen. in the meanwhile, if you feel that you can improve on the current documentation, here is the file: https://github.com/mootools/mootools-core/blob/master/Docs/Element/Element.md#element-method-empty-elementempty - fork, clone, make a branch quoting this issue, edit/update, test, push, send pull request.