rearranging internal API to support better documentation, documenting everything