Let's try documenting this API

Note that the actual behavior is not perfectly this yet