document most of the public interface