For the BGE the api is enough, though a link to KX_Object and KX_Scene would be good. For the addons the API in not very clear, I prefer to look at the code of other addons that implement something similar to what I want to. By the way, I always use this website, building the API yourself is a nightmare.