Document undocumented API method

also added corresponding assertion