Work around issue #36, improve Core API documentation

I did put the suggest work around into the API itself.