I think you just described a man page. Except for the xml part. That sounds a lot more like something MS would do.
I agree that this might lead to something which is not in Unix spirit but already shell completion provide such information and this shows the need for such specs.