document API method and add assertion