IMO, a better name for the functions would be nice (since changing later breaks plugins), but at the very least the doc-comments should be more detailed to better explain what the functions do without referring to other stuff that isn't linkable inside the plugin API docs.