more comments and todo for more complete api