add a bit more documentation of interfaces