documenting some of the more accessible api