add INTERNAL API markers and explicit return types