A couple years down the road from the start of this thread but it now appears good news has finally emerged concerning this topic.
It looks like around the same time of those comments by by @RobM and @matjaz, that RobM was tasked by Matjaz to commence work on developing documentation for the Developer API.
So the forth coming Developer API documentation should end up being pretty comprehensive after seeing some of RobM’s previous work.
Thanks @RobM, looking forward to it.