Cosmos docstring review - #8607
Merged
Merged
Conversation
|
Can one of the admins verify this patch? |
Closed
annatisch
approved these changes
Nov 14, 2019
xiangyan99
added a commit
that referenced
this pull request
Nov 15, 2019
* InteractiveBrowserCredential prompts for account selection (#8470) * remove *.yaml under tests folder from manifest.in (#8625) * [AutoPR] cosmos-db/resource-manager (#8560) * regenerated * fix script * another place * fix * fix * one more change * one more * undo multiapi script * regeneated * undo multiapi script * history, version + additional fix * regenerated * fixed test * fixed generation mistake * added more breaking changes to history * regenerated again * additional fixes * udpated test names * test recordings * Update README.md (#8628) Add standard section on security issues below the "file an issue via GitHub Issues' bullet. * Handle exceptions when constructing DefaultAzureCredential (#8294) * Python 3.8 test pipeline is not cancelled when build is cancelled (#8544) * Skip python 3.8 testing when CI is cancelled * Cosmos docstring review (#8607) * cosmos docstring edits * user-defined * trailing whitespace * xfail flaky emulator tests * review feedback * Default credentials are configurable by kwargs (#8514) * Nightly build is failing due version conflict between storage datalak… (#8635) * Nightly build is failing due version conflict between storage datalake and storage blob * InkRecognizer to use GA azure-core (#8341) * InkRecognizer to use Ga azure-core * Disable auto-pr update * Azconfig remove tests from whl (#8663) * update tests * ignoring the azure folder directly (#8673)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
issues: closes #7788 closes #8624
cc @annatisch
Proposed to move documentation of "common kwargs" to a separate issue/PR.
A few comments:
I'm old fashioned and still read often docstrings in a terminal. I definitely appreciate when text/paras in docstrings are < ~80 cols, so I have tried to hew to that.
My perception is that the preference in the repo is for args lists that are vertically compact, so I have made some edits around that as well.
Besides typo, grammar fixes, I tried to implement parallel phrasing in places where it was simple and made sense.
Added notes about some exceptions up front (e.g. API for deleting a non-existent item could go either way, as a user I'd like to know immediately I need to basically always wrap with a
try/except)It would be an interesting exercise to review use of tense and number in docstrings across all the projects. I am personally in the (Calling this function will) "Update a specified document widget" camp, and not the (A call to this function) "Updates the specified document widget" camp.