I use neovim heavily and I spend the first five minutes of my morning thanking the developers for their hard work - without their selflessness we wouldn't have the best text editor in the world. I was just commenting on whether the purported benefits of using Lua over Vimscript as the core scripting language really panned out. Clearly a lot of people think they did.
I haven't implemented this yet, but one thing I'm looking forward to is lua libraries. I have a data YAML that carries some autocomplete information. To use it with a vimscript function I had to convert it to a JSON first. With lua I should be able to use a library to just read the YAML directly.
The API is pretty well documented now I think? If there is a specific area that isn't, then file a bug or write the docs. It is an open source project and thus is heavily depends on people contributing to make things better.