In general, the API docs need to be improved a lot for example to filter by `@api` tag, filter out internal methods and so much more. But I think that's outside of the scope of this PR. I want to get a good wording of the BC promise out first.