Skip to content

docs: streamline docstrings for conditional parmas #464

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.

Sign up for GitHub

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

Jump to bottom
Merged
tseaver merged 6 commits into from
Jun 21, 2021
Merged

docs: streamline docstrings for conditional parmas #464

tseaver merged 6 commits into from
Jun 21, 2021

Conversation

@tseaver
Copy link
Contributor

@tseaver tseaver commented Jun 10, 2021 •
edited
Loading

Add narrative docs for conditional params:

  • 'if_generation_match'
  • 'if_generation_not_match'
  • 'if_metageneration_match'
  • 'if_metageneration_not_match'

Replace verbose docstring entries for those params with links to the narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.

Closes #460.

@tseaver tseaver requested review from a team, andrewsg, cojenco, frankyn and tritone June 10, 2021 18:42
@tseaver tseaver requested a review from a team as a code owner June 10, 2021 18:42
@product-auto-label product-auto-label bot added the api: storage Issues related to the googleapis/python-storage API. label Jun 10, 2021
@google-cla google-cla bot added the cla: yes This human has signed the Contributor License Agreement. label Jun 10, 2021
This was referenced Jun 11, 2021
Merged
Merged
@tseaver tseaver added the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jun 11, 2021
@tseaver
Copy link
Contributor Author

tseaver commented Jun 11, 2021 •
edited
Loading

Blocked pending merges of:

@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from d8ad3ee to 1b2ef92 Compare June 14, 2021 15:52
@tseaver tseaver removed the do not merge Indicates a pull request not ready for merge, due to either quality or timing. label Jun 14, 2021
@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 1b2ef92 to 0d296b0 Compare June 15, 2021 17:19
@tseaver tseaver added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 18, 2021
@yoshi-kokoro yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 18, 2021
@tseaver
Copy link
Contributor Author

tseaver commented Jun 18, 2021

@cojenco, @andrewsg ready for review.

tseaver added 2 commits June 21, 2021 13:01
@tseaver
docs: add narrative docs for conditional params
c502a92 
- 'if_genration_match'
- 'if_genration_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'

Toward #460.
@tseaver
docs: streamline docstrings for conditional parmas
7c04114 
Link to new narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present)
for consistency.

Closes #460.
@tseaver tseaver force-pushed the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch from 4a8fa65 to 7c04114 Compare June 21, 2021 17:01
@tseaver
Copy link
Contributor Author

tseaver commented Jun 21, 2021

@frankyn, @tritone, @andrewsg, @cojenco PTAL.

@cojenco
Copy link
Contributor

cojenco commented Jun 21, 2021

Thanks for the ping, @tseaver . Taking a look now.

cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
cojenco
cojenco reviewed Jun 21, 2021
View reviewed changes
cojenco
cojenco requested changes Jun 21, 2021
View reviewed changes
Copy link
Contributor

@cojenco cojenco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks @tseaver for adding the generation/preconditions reference doc and streamlining the docstrings. Looks so much better! A few comments and nits, otherwise, LGTM

tseaver added 2 commits June 21, 2021 14:27
@tseaver
docs: add prologue, linking concepts
b9367f4 
Addressing review comment.
@tseaver
docs: wording changes / typo fixes
e8f2479 
Addressing review comments.
@tseaver tseaver requested a review from cojenco June 21, 2021 18:32
cojenco
cojenco approved these changes Jun 21, 2021
View reviewed changes
Copy link
Contributor

@cojenco cojenco left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM, thanks!

danielduhh
danielduhh reviewed Jun 21, 2021
View reviewed changes
Copy link
Contributor

@danielduhh danielduhh left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Just one super nit -- also looks like Kokoro is failing

@dandhlee
Copy link
Contributor

dandhlee commented Jun 21, 2021

docfx and docs-presubmit will fail, sorry about that! If if's just those two and you can move the PR along then please do so, otherwise you'll have to wait until I resolve it with googleapis/sphinx-docfx-yaml#48.

@dandhlee dandhlee added the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 21, 2021
@yoshi-kokoro yoshi-kokoro removed the kokoro:force-run Add this label to force Kokoro to re-run the tests. label Jun 21, 2021
@dandhlee
Copy link
Contributor

dandhlee commented Jun 21, 2021

Everything is fixed! Sorry to make you wait 😅

@tseaver tseaver merged commit 6999370 into master Jun 21, 2021
@tseaver tseaver deleted the 460-move-boilerplate-gen-metagen-docs-from-docstrings branch June 21, 2021 22:31
cojenco pushed a commit to cojenco/python-storage that referenced this pull request Oct 13, 2021
@tseaver @cojenco
docs: streamline docstrings for conditional parmas (googleapis#464)
506e883 
Add narrative docs for conditional params:

- 'if_generation_match'
- 'if_generation_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'

Streamline docstrings for conditional params, linking to new narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.

Closes googleapis#460.
cojenco pushed a commit to cojenco/python-storage that referenced this pull request Oct 13, 2021
@tseaver @cojenco
docs: streamline docstrings for conditional parmas (googleapis#464)
04dd1e3 
Add narrative docs for conditional params:

- 'if_generation_match'
- 'if_generation_not_match'
- 'if_metageneration_match'
- 'if_metageneration_not_match'

Streamline docstrings for conditional params, linking to new narrative docs.

Also, move 'timeout' argument to end (just before 'retry', if present) for consistency.

Closes googleapis#460.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@danielduhh danielduhh danielduhh left review comments

@cojenco cojenco cojenco approved these changes

@andrewsg andrewsg Awaiting requested review from andrewsg

@frankyn frankyn Awaiting requested review from frankyn

@tritone tritone Awaiting requested review from tritone

Assignees

No one assigned

Labels

api: storage Issues related to the googleapis/python-storage API. cla: yes This human has signed the Contributor License Agreement.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

Move boilerplate docs for 'if_generation_match' et al. out of method docstrings

5 participants

@tseaver @cojenco @dandhlee @danielduhh @yoshi-kokoro