[docs] Simple, yet effective, example use of each API method

[gregfenton]

Is your feature request related to a problem? Please describe. Get a Node/Javascript developer who is not familiar with this API set to use just the published documentation from this project to figure out how to use geocode(). The information is here, but it involved me following links to several other Google Maps projects/APIs, having to decode examples not using geocode(), and trying to leverage the info at this page that was ... not straightforward.

Describe the solution you'd like

A simple, "realistic" example of the invocation of each API. For example for geocode() it could be:

import { Client } from '@googlemaps/google-maps-services-js';

const run = async () => {
  const client = new Client();
  const result = await client.geocode({ params: {
    key: '<key>',
    address: 'Perth 4WD & Commercial Centre',
  } });
  console.log(result.data.results[0].types);
};

run();

Describe alternatives you've considered

Google searches, YouTube views, and eventually figured things out by looking over Issues for this very GitHub repo.

Additional context

The info is here. But it isn't readily "accessible". It involves a lot of jumps. Could be simpler with just a few lines of docs.

[jpoehnelt]

This runs into the perpetual challenge of keeping functioning code snippets in documentation. At this time I do not have a solution other than linking to the e2e tests folder.

[jpoehnelt]

@gregfenton Do you use TypeScript?

[gregfenton]

@gregfenton Do you use TypeScript?

I do not.

[gregfenton]

This runs into the perpetual challenge of keeping functioning code snippets in documentation.

Directionally correct is more important than perfectly correct "copy-n-paste" examples.

At this time I do not have a solution other than linking to the e2e tests folder.

First, many API documentations have examples in them. This is not a new pattern.

Second, I would be fine with pointing to any test code as long as those tests showcase "realistic uses" rather than just passing in trivial and meaningless data (i.e. use a real address, or real lat/long values, etc. Show how to work with the return values. This is what took time to figure out when just looking at the API docs themselves. See the above example...it shouldn't take several searches to pull together a few lines of code.)

Thanks for the consideration!

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. Please comment here if it is still valid so that we can reprioritize. Thank you!

[gregfenton]

I'll happily submit a docs PR, if someone would provide direction as to where such an above example should be submitted. Or maybe a pointer to a guide on documentation for this project so I am submitting something inline with the "docs standard".

[jpoehnelt]

It should be possible to add examples to the comments using markdown syntax and the running npm run docs to see the output.

The docs are generated by TypeDoc, see https://typedoc.org/guides/doccomments/#code-blocks.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. Please comment here if it is still valid so that we can reprioritize. Thank you!

[stale[bot]]

Closing this. Please reopen if you believe it should be addressed. Thank you for your contribution.

[gregfenton]

@jpoehnelt When I run npm run docs, the docs folder is created and files are generated but I do not see the particular documentation page this issue describes. Should I not be finding a file ./docs/modules/_geocode_geocode_.html ?

I am adding a code snippet example to src/geocode/geocode.ts. But grep'ing all of ./docs I do not find my code?

[jpoehnelt]

Might need to document the method in https://github.com/googlemaps/google-maps-services-js/blob/master/src/client.ts on the Client class. I'm guessing that is why they are not showing up. The non client api functions are not documented in the ref docs because they aren't exported in the index.ts.

[wangela]

These all follow the same pattern demonstrated in the README on GitHub,, NPM, and in the docs. That example plus an inspection of the supported params provides the necessary information to form a working request.