docs: clarify fields usage and UTF-8 subjects for gmail raw drafts

[sonwr]

Fixes #266

Adds concise docs for two common pitfalls:

• response fields should be passed inside --params JSON
• non-ASCII Gmail raw subjects should use RFC 2047 encoded-word format

Also adds copy-paste examples in README troubleshooting/advanced usage.

[changeset-bot]

⚠️ No Changeset found

Latest commit: bd4a655

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[google-cla]

Thanks for your pull request! It looks like this may be your first contribution to a Google open source project. Before we can look at your pull request, you'll need to sign a Contributor License Agreement (CLA).

View this failed invocation of the CLA check for more information.

For the most up to date status, view the checks section at the bottom of the pull request.

[gemini-code-assist]

Summary of Changes

Hello, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request enhances the documentation by addressing two common issues encountered when interacting with Google APIs. It clarifies the correct usage of the fields parameter for Discovery API methods, emphasizing its inclusion within the --params JSON. Additionally, it provides essential guidance and a practical example for handling non-ASCII UTF-8 subjects in Gmail raw drafts, ensuring proper encoding. These updates aim to prevent common pitfalls and improve the developer experience.

Highlights

• Clarified fields parameter usage: Documentation was added to clarify that for Discovery API methods, the fields selection should be included within the --params JSON, rather than as a standalone flag, to avoid errors or ignored output filtering.
• Guidance for UTF-8 subjects in Gmail raw drafts: New documentation and a copy-paste example were provided for handling non-ASCII subject headers in Gmail raw drafts, instructing users to use RFC 2047 encoded-word format and ensure UTF-8 awareness for message headers and body.

Changelog

• README.md
  • Added a section clarifying that fields selection lives inside --params.
  • Added a section on handling UTF-8 subject headers for Gmail raw drafts.
  • Added a troubleshooting section for --fields errors or ignored output filtering.
  • Added a troubleshooting section for garbled Gmail draft/send subjects with non-ASCII text.

Activity

• No activity has been recorded for this pull request yet.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	/gemini review	Performs a code review for the current pull request in its current state.
Pull Request Summary	/gemini summary	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	/gemini help	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Footnotes

1. Review the Generative AI Prohibited Use Policy, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

[gemini-code-assist]

Code Review

This pull request adds valuable documentation to the README, clarifying common pitfalls with fields usage and encoding non-ASCII subjects in raw Gmail drafts. The examples are very helpful for users. I've found one small but important correction for the raw Gmail message example to ensure it strictly adheres to RFC 2822 standards, which is detailed in the review comment.

[googleworkspace-bot]

/gemini review

[gemini-code-assist]

Code Review

This pull request adds documentation to README.md clarifying the usage of the fields parameter and the encoding of UTF-8 subjects for raw Gmail drafts. The changes introduce new sections with examples in the 'Advanced Usage' and 'Troubleshooting' parts of the document. The review of these documentation changes did not identify any issues requiring action.

[sonwr]

Quick follow-up: all current review comments are addressed, all visible checks are passing, and the PR is ready for maintainer review/merge when you have a moment. Thank you!