Basic as this is, I think a brief doc block is still valuable. You can just copy in what you put in the REST API docs. I hope that one day our REST API docs will be auto-generated from these doc blocks, so it's valuable to keep these as the primary source.