dd32 has written some basics about the plugin API: http://dd32.id.au/projects/wordpressorg-plugin-information-api-docs/ I agree that some more in depth docs in an authoritative location would be good.