All I know about Vala is what you've written, but given that, I do agree
it would be useful to document it. So a doc patch would be most welcome.