-
Notifications
You must be signed in to change notification settings - Fork 592
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Lack of developer documentation #479
Comments
Hi @ludoch thanks for the feedback. We pride ourselves on our documentation so it's sad to hear you're not satisfied. Datastore is a rather tricky API to make an idiomatic client for while also giving users like you the ability to do everything you need to do. This is because the Datastore concepts are strongly linked to the API itself, e.g. what a key is, what an entity is, how these play in when you're just trying to save your data to the datastore. We hope this library tries to soften the edges by abstracting away the details that don't matter and in some cases making assumptions on what you want to do given the specific context. In any case, we believe that as a developer you should ramp yourself up on the various high level concepts of each API from https://cloud.google.com/docs/. We should also likely make this clear in our docs.
This is just talking about the We'd suggest you start looking at the
If you believe that other languages documentation is also bad, I'd suggest you open separate issues on their libraries for your concerns as different people work on different libraries. |
It would be nice to add in a quick link in each module's "overview" section to the official docs. |
Sent in #507 that links to Google developer docs for each service. This will hopefully give newcomers an easy path to all the information they will need. |
[![WhiteSource Renovate](https://app.renovatebot.com/images/banner.svg)](https://renovatebot.com) This PR contains the following updates: | Package | Change | Age | Adoption | Passing | Confidence | |---|---|---|---|---|---| | [@types/node](https://togithub.com/DefinitelyTyped/DefinitelyTyped) | [`^12.0.0` -> `^14.0.0`](https://renovatebot.com/diffs/npm/@types%2fnode/12.20.13/14.17.0) | [![age](https://badges.renovateapi.com/packages/npm/@types%2fnode/14.17.0/age-slim)](https://docs.renovatebot.com/merge-confidence/) | [![adoption](https://badges.renovateapi.com/packages/npm/@types%2fnode/14.17.0/adoption-slim)](https://docs.renovatebot.com/merge-confidence/) | [![passing](https://badges.renovateapi.com/packages/npm/@types%2fnode/14.17.0/compatibility-slim/12.20.13)](https://docs.renovatebot.com/merge-confidence/) | [![confidence](https://badges.renovateapi.com/packages/npm/@types%2fnode/14.17.0/confidence-slim/12.20.13)](https://docs.renovatebot.com/merge-confidence/) | --- ### Configuration 📅 **Schedule**: "after 9am and before 3pm" (UTC). 🚦 **Automerge**: Disabled by config. Please merge this manually once you are satisfied. ♻️ **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. 🔕 **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box. --- This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#github/googleapis/nodejs-redis).
This PR contains the following updates: | Package | Type | Update | Change | |---|---|---|---| | [google-auth-library](https://togithub.com/googleapis/google-auth-library-nodejs) | devDependencies | major | [`^5.7.0` -> `^6.0.0`](https://renovatebot.com/diffs/npm/google-auth-library/5.10.1/6.0.0) | --- ### Release Notes <details> <summary>googleapis/google-auth-library-nodejs</summary> ### [`v6.0.0`](https://togithub.com/googleapis/google-auth-library-nodejs/blob/master/CHANGELOG.md#​600-httpswwwgithubcomgoogleapisgoogle-auth-library-nodejscomparev5101v600-2020-03-26) [Compare Source](https://togithub.com/googleapis/google-auth-library-nodejs/compare/v5.10.1...v6.0.0) ##### ⚠ BREAKING CHANGES - typescript@3.7.x introduced some breaking changes in generated code. - require node 10 in engines field ([#​926](https://togithub.com/googleapis/google-auth-library-nodejs/issues/926)) - remove deprecated methods ([#​906](https://togithub.com/googleapis/google-auth-library-nodejs/issues/906)) ##### Features - require node 10 in engines field ([#​926](https://www.github.com/googleapis/google-auth-library-nodejs/issues/926)) ([d89c59a](https://www.github.com/googleapis/google-auth-library-nodejs/commit/d89c59a316e9ca5b8c351128ee3e2d91e9729d5c)) ##### Bug Fixes - do not warn for SDK creds ([#​905](https://www.github.com/googleapis/google-auth-library-nodejs/issues/905)) ([9536840](https://www.github.com/googleapis/google-auth-library-nodejs/commit/9536840f88e77f747bbbc2c1b5b4289018fc23c9)) - use iamcredentials API to sign blobs ([#​908](https://www.github.com/googleapis/google-auth-library-nodejs/issues/908)) ([7b8e4c5](https://www.github.com/googleapis/google-auth-library-nodejs/commit/7b8e4c52e31bb3d448c3ff8c05002188900eaa04)) - **deps:** update dependency gaxios to v3 ([#​917](https://www.github.com/googleapis/google-auth-library-nodejs/issues/917)) ([1f4bf61](https://www.github.com/googleapis/google-auth-library-nodejs/commit/1f4bf6128a0dcf22cfe1ec492b2192f513836cb2)) - **deps:** update dependency gcp-metadata to v4 ([#​918](https://www.github.com/googleapis/google-auth-library-nodejs/issues/918)) ([d337131](https://www.github.com/googleapis/google-auth-library-nodejs/commit/d337131d009cc1f8182f7a1f8a9034433ee3fbf7)) - **types:** add additional fields to TokenInfo ([#​907](https://www.github.com/googleapis/google-auth-library-nodejs/issues/907)) ([5b48eb8](https://www.github.com/googleapis/google-auth-library-nodejs/commit/5b48eb86c108c47d317a0eb96b47c0cae86f98cb)) ##### Build System - update to latest gts and TypeScript ([#​927](https://www.github.com/googleapis/google-auth-library-nodejs/issues/927)) ([e11e18c](https://www.github.com/googleapis/google-auth-library-nodejs/commit/e11e18cb33eb60a666980d061c54bb8891cdd242)) ##### Miscellaneous Chores - remove deprecated methods ([#​906](https://www.github.com/googleapis/google-auth-library-nodejs/issues/906)) ([f453fb7](https://www.github.com/googleapis/google-auth-library-nodejs/commit/f453fb7d8355e6dc74800b18d6f43c4e91d4acc9)) ##### [5.10.1](https://www.github.com/googleapis/google-auth-library-nodejs/compare/v5.10.0...v5.10.1) (2020-02-25) ##### Bug Fixes - if GCF environment detected, increase library timeout ([#​899](https://www.github.com/googleapis/google-auth-library-nodejs/issues/899)) ([2577ff2](https://www.github.com/googleapis/google-auth-library-nodejs/commit/2577ff28bf22dfc58bd09e7365471c16f359f109)) </details> --- ### Renovate configuration :date: **Schedule**: "after 9am and before 3pm" (UTC). :vertical_traffic_light: **Automerge**: Disabled by config. Please merge this manually once you are satisfied. :recycle: **Rebasing**: Whenever PR is behind base branch, or you tick the rebase/retry checkbox. :no_bell: **Ignore**: Close this PR and you won't be reminded about this update again. --- - [ ] <!-- rebase-check -->If you want to rebase/retry this PR, check this box --- This PR has been generated by [WhiteSource Renovate](https://renovate.whitesourcesoftware.com). View repository job log [here](https://app.renovatebot.com/dashboard#googleapis/nodejs-translate).
🤖 I have created a release \*beep\* \*boop\* --- ### [2.4.4](https://www.github.com/googleapis/nodejs-cloud-container/compare/v2.4.3...v2.4.4) (2021-08-17) ### Bug Fixes * **deps:** google-gax v2.24.1 ([#477](https://www.github.com/googleapis/nodejs-cloud-container/issues/477)) ([11bdd83](https://www.github.com/googleapis/nodejs-cloud-container/commit/11bdd83b4c676b9c10608c9f505a10261f2bb939)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
…butes (#479) * feat: Add connection and description field to finding's list of attributes PiperOrigin-RevId: 442589635 Source-Link: googleapis/googleapis@50fc834 Source-Link: googleapis/googleapis-gen@86cc920 Copy-Tag: eyJwIjoiLmdpdGh1Yi8uT3dsQm90LnlhbWwiLCJoIjoiODZjYzkyMDUyOWIwODc3YmE4MTIxNmI1MmQ5OTVjZTRkZDJmOGI0ZiJ9 * 🦉 Updates from OwlBot post-processor See https://github.com/googleapis/repo-automation-bots/blob/main/packages/owl-bot/README.md Co-authored-by: Owl Bot <gcf-owl-bot[bot]@users.noreply.github.com>
🤖 I have created a release \*beep\* \*boop\* --- ## [2.4.0](https://www.github.com/googleapis/nodejs-automl/compare/v2.3.1...v2.4.0) (2021-01-09) ### Features * adds style enumeration ([#478](https://www.github.com/googleapis/nodejs-automl/issues/478)) ([1eddaf2](https://www.github.com/googleapis/nodejs-automl/commit/1eddaf2618a1e65d3f54faba4e1ef37abcdab916)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
🤖 I have created a release \*beep\* \*boop\* --- ### [2.2.2](https://www.github.com/googleapis/nodejs-dns/compare/v2.2.1...v2.2.2) (2021-08-09) ### Bug Fixes * **build:** migrate to using main branch ([#478](https://www.github.com/googleapis/nodejs-dns/issues/478)) ([2f19b00](https://www.github.com/googleapis/nodejs-dns/commit/2f19b0066a26910262abff94974c55cda41b3fae)) --- This PR was generated with [Release Please](https://github.com/googleapis/release-please). See [documentation](https://github.com/googleapis/release-please#release-please).
See https://googlecloudplatform.github.io/gcloud-node/#/docs/v0.13.1/datastore
It mentions "some convenience methods"
Convenience based on What?
Do I need to master the low level Datastore APIs? Imo, the gcloud layer should be self sufficient and complete for documentation, exposing all the Datastore concepts assuming the user knows nothing, and without the need for the user to read other docs....
The doc issue seems generic for all gcloud APIs for all the runtimes (same for Java, I did not look at ruby)
The text was updated successfully, but these errors were encountered: