docs.

[stephenplusplus]

RE: #19

Did a sweep of the Datastore doc blocks, as well as laid the groundwork for docs to come. Thanks to jsdoc2md, 5 files are generated in a new docs directory, one for each service/module: "Common", "Datastore", "PubSub", "Storage", and one for lib/index, which is generated as the default "readme.md" for the directory.

For a look at the rendered results, see https://github.com/stephenplusplus/gcloud-node/blob/docs/docs/datastore.md

[rakyll]

Looks like a great start. Quick question, should be move the internal modules such as datastore/entity to another directory to exclude them from docs or annotate them with private?

[beriberikix]

+1 for marking private methods. Also, what's with random eject icon only on the classes?

[stephenplusplus]

@rakyll I went over entity, and marked all but 3 methods as private: Key, Int, and Double - they aren't used directly by the consumer, but as they are already documented in entity.js, I kept them public so our datastore helper methods (datastore.key, datastore.int, and datastore.double) could use their docs.

However, I think jsdoc2md may have a bug, as it doesn't seem to recognize @borrows, which should handle making that link connection. The same code works as expected when outputting jsdoc HTML directly.

https://github.com/stephenplusplus/gcloud-node/blob/docs/docs/datastore.md#datastoreentity

[stephenplusplus]

Updated 💯

[rakyll]

I was thinking we should also provide examples for user facing calls -- mostly what we cover on the README. We don't have bandwidth to maintain samples all across the client. And most of them are tautological, reading JSDocs would give an idea.

@silvolu thinks similarly AFAIK.

[silvolu]

Yep! After a quick skim most of it looks already covered, I the only missing one I could see are for CRUD operations in datastore/entity.js: you're borrowing from transaction, but that will pull in the transaction code sample as well right?

[stephenplusplus]

I believe most of the readme Dataset examples are covered.

@silvolu I think you meant datastore/dataset.js. Like you said, those are linked to transaction, so the docs would link over to the signature and examples from there. That's at least how the official JSDoc interpreter will see them; if we decide on a tool to output the docs that doesn't support @borrows, we would probably have to double up on our definitions.

[silvolu]

Yeah sorry, that's what I meant. Wouldn't the resulting sample be incorrect though? (e.g. ds.get vs transaction.get)

[stephenplusplus]

Yeah, it would show the examples in the context of a transaction. We can override the examples for those, hopefully still allowing the description/signature to match. We would end up with identical examples (minus the object name change), but if you think that's a fair price, I'll be happy to override 👍

[silvolu]

Yeah, I think this one is a small dup that we need: the relation between the dataset operation and the transaction might not be immediately clear, and the sample could confuse the user.
Thanks!

[stephenplusplus]

No problemo! I'll probably save that for tomorrow. Feel free to merge as-is if this is blocking anything, I can always send another PR for the example updates.

[rakyll]

I'm merging this, then.