Skip to content
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

Closed
ludoch opened this issue Apr 3, 2015 · 3 comments · Fixed by #507
Closed

Lack of developer documentation #479

ludoch opened this issue Apr 3, 2015 · 3 comments · Fixed by #507
Assignees
Labels
🚨 This issue needs some love. triage me I really want to be triaged.

Comments

@ludoch
Copy link

ludoch commented Apr 3, 2015

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)

@ryanseys
Copy link
Contributor

ryanseys commented Apr 3, 2015

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.

"some convenience methods"

This is just talking about the datastore#double and datastore#int methods available on that object for specifying the type of number you'd like to save to the datastore because JavaScript only has a single number type.

We'd suggest you start looking at the dataset documentation because that gives you the power to make calls with the API. We should also make this more clear in our documentation.

The doc issue seems generic for all gcloud APIs for all the runtimes

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.

@stephenplusplus
Copy link
Contributor

It would be nice to add in a quick link in each module's "overview" section to the official docs.

stephenplusplus added a commit to stephenplusplus/gcloud-node that referenced this issue Apr 21, 2015
stephenplusplus added a commit to stephenplusplus/gcloud-node that referenced this issue Apr 21, 2015
@stephenplusplus
Copy link
Contributor

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.

stephenplusplus added a commit to stephenplusplus/gcloud-node that referenced this issue Apr 27, 2015
stephenplusplus added a commit to stephenplusplus/gcloud-node that referenced this issue Apr 27, 2015
@yoshi-automation yoshi-automation added triage me I really want to be triaged. 🚨 This issue needs some love. labels Apr 6, 2020
sofisl pushed a commit that referenced this issue Sep 15, 2022
[![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).
sofisl pushed a commit that referenced this issue Sep 27, 2022
sofisl pushed a commit that referenced this issue Nov 9, 2022
sofisl pushed a commit that referenced this issue Nov 10, 2022
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#&#8203;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 ([#&#8203;926](https://togithub.com/googleapis/google-auth-library-nodejs/issues/926))
-   remove deprecated methods ([#&#8203;906](https://togithub.com/googleapis/google-auth-library-nodejs/issues/906))

##### Features

-   require node 10 in engines field ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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 ([#&#8203;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).
sofisl pushed a commit that referenced this issue Nov 11, 2022
Co-authored-by: release-please[bot] <55107282+release-please[bot]@users.noreply.github.com>
sofisl pushed a commit that referenced this issue Nov 18, 2022
…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>
sofisl pushed a commit that referenced this issue Jan 17, 2023
sofisl pushed a commit that referenced this issue Jan 24, 2023
sofisl pushed a commit that referenced this issue Jan 25, 2023
sofisl pushed a commit that referenced this issue Sep 13, 2023
sofisl pushed a commit that referenced this issue Sep 14, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
🚨 This issue needs some love. triage me I really want to be triaged.
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants