GoogleCloudPlatform/gcloud-node — pull request #209 by ryanseys (2014-09-13 16:52:52+00:00)
Title: Entity.key() docs + proposal for simpler API

There were no docs at all for Entity.key() so I added some here. They are not perfect though because the weird param structure used for the function.

Currently the params are something like either:

| Name | Type |
| -------- | ------- |
| options | `object` |
| options.namespace | `string` |
| options.path | `array` |

or

| Name | Type |
| -------- | ------- |
| path | *any type*, passed in as arguments list |

#### Issues:

1. That's really hard to document... I don't even know how to do it here, let alone in valid JSDoc (don't think it's possible, think you need something like a `@paramset`: [what is suggested here](https://code.google.com/p/jsdoc-toolkit/issues/detail?id=202))
2. That's really hard to understand, even if documented.
3. If I have a path array, only option I have is use the first option and know that `this.namespace` exists or manually provide it, or I can use [`Function.apply`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function/apply) to apply the array to the function as arguments (yikes!)

#### Proposal (not implemented here):

Just accept an object, specifying path. It's not hard to understand, document and requires only 9 characters extra for the developer to surround their old arguments for this new method:

`.key({ path: [ ] })`

| Name | Type | Optional |
| -------- | ------- | ----------- |
| options | `object` | `false` |
| options.namespace | `string` | `true` (use `this.namespace` if not provided) |
| options.path | `array` | `false` |