intridea/grape — pull request #183 by flah00 (2012-06-11 19:28:29+00:00)
Title: Added documentation to entities

Entities and documentation seem like a logical unit. Combining inheritable exposures with inheritable docs would be magical! I am currently forced to define a hash (object_fields) in a call to desc and maintain an entity and documentation separately.

My current work flow

1. Create an entity
1. Create an endpoint
1. Write a desc for the endpoint

```
desc "blah blah", {
:params => {
:slug => { :type => "string", :desc => "unique id" }
},
:object_fields => {
:slug => { :type => "string", :desc => "unique id" },
:name => { :type => "string", :desc => "the name of the object" }
}
}
```

Inevitably, our very immature API requires field fiddling and I have to revisit the entity. Suddenly I'm faced with the very frustrating prospect of changing the desc and the entity ... and I don't always remember. When I add something to the entity, I need to remember to add it to the object_fields hash as well.

If entities become aware of one more key, maybe called documentation, I could gain immediate visibility into which fields are and aren't documented... and I'd be happier.