Fix and improve documentation throughout the API.
Review Request #8774 — Created Feb. 21, 2017 and submitted
We had a number of places where our API documentation was incorrect, incomplete, or just not consistent with other parts of the documentation. This change fixes a handful of these cases throughout the API codebase. The simplest changes introduce double backticks for text that should be literals. There's a large number of these, and they're going to make a big difference with an upcoming change for the website. There were older APIs that documented request arguments in the HTTP method's docs instead of defining fields. These have been replaced with @webapi_request_fields decorators. We also had a few of these decorators that were including some incorrect information due to augmenting details from other resources, so those have been fixed. Some documentation has moved from class/method docstrings into field docs. This will look good with the upcoming changes for the website. We also just simply had some missing/incomplete documentation, which has been added/rewritten.
Went through every single API page we had and verified the contents
appeared sane and consistent.These changes are tested along with an upcoming change for API doc
generation and website styling.
| Description | From | Last Updated |
|---|---|---|
|
'WebAPIResource' imported but unused |
 reviewbot
|
-
Tool: PEP8 Style Checker Processed Files: reviewboard/webapi/resources/base_comment.py reviewboard/webapi/resources/review_request_draft.py reviewboard/webapi/resources/repository_commits.py reviewboard/webapi/resources/remote_repository.py reviewboard/webapi/resources/review_file_attachment_comment.py reviewboard/webapi/resources/change.py reviewboard/webapi/resources/diff_context.py reviewboard/webapi/resources/review_request.py reviewboard/webapi/resources/default_reviewer.py reviewboard/webapi/resources/review_group_user.py reviewboard/webapi/resources/base_review.py reviewboard/webapi/resources/diff.py reviewboard/webapi/resources/repository_branches.py reviewboard/webapi/resources/hosting_service_account.py reviewboard/webapi/resources/session.py reviewboard/webapi/resources/api_token.py reviewboard/webapi/resources/review_request_last_update.py reviewboard/webapi/resources/user.py reviewboard/webapi/resources/base_diff_comment.py
- Change Summary:
-
Removed an unused import.
- Commit:
-
9dca6cf816ad97928d5a28f529ddca4504b29e3676093d00c49b4be12588952184109dbdafaa5a21
- Diff:
-
Revision 2 (+271 -183)
-
Tool: Pyflakes Processed Files: reviewboard/webapi/resources/base_comment.py reviewboard/webapi/resources/review_request_draft.py reviewboard/webapi/resources/repository_commits.py reviewboard/webapi/resources/remote_repository.py reviewboard/webapi/resources/review_file_attachment_comment.py reviewboard/webapi/resources/change.py reviewboard/webapi/resources/diff_context.py reviewboard/webapi/resources/review_request.py reviewboard/webapi/resources/default_reviewer.py reviewboard/webapi/resources/review_group_user.py reviewboard/webapi/resources/base_review.py reviewboard/webapi/resources/diff.py reviewboard/webapi/resources/repository_branches.py reviewboard/webapi/resources/hosting_service_account.py reviewboard/webapi/resources/session.py reviewboard/webapi/resources/api_token.py reviewboard/webapi/resources/review_request_last_update.py reviewboard/webapi/resources/user.py reviewboard/webapi/resources/base_diff_comment.py
-
Tool: PEP8 Style Checker Processed Files: reviewboard/webapi/resources/base_comment.py reviewboard/webapi/resources/review_request_draft.py reviewboard/webapi/resources/repository_commits.py reviewboard/webapi/resources/remote_repository.py reviewboard/webapi/resources/review_file_attachment_comment.py reviewboard/webapi/resources/change.py reviewboard/webapi/resources/diff_context.py reviewboard/webapi/resources/review_request.py reviewboard/webapi/resources/default_reviewer.py reviewboard/webapi/resources/review_group_user.py reviewboard/webapi/resources/base_review.py reviewboard/webapi/resources/diff.py reviewboard/webapi/resources/repository_branches.py reviewboard/webapi/resources/hosting_service_account.py reviewboard/webapi/resources/session.py reviewboard/webapi/resources/api_token.py reviewboard/webapi/resources/review_request_last_update.py reviewboard/webapi/resources/user.py reviewboard/webapi/resources/base_diff_comment.py
Tool: Pyflakes Processed Files: reviewboard/webapi/resources/base_comment.py reviewboard/webapi/resources/review_request_draft.py reviewboard/webapi/resources/repository_commits.py reviewboard/webapi/resources/remote_repository.py reviewboard/webapi/resources/review_file_attachment_comment.py reviewboard/webapi/resources/change.py reviewboard/webapi/resources/diff_context.py reviewboard/webapi/resources/review_request.py reviewboard/webapi/resources/default_reviewer.py reviewboard/webapi/resources/review_group_user.py reviewboard/webapi/resources/base_review.py reviewboard/webapi/resources/diff.py reviewboard/webapi/resources/repository_branches.py reviewboard/webapi/resources/hosting_service_account.py reviewboard/webapi/resources/session.py reviewboard/webapi/resources/api_token.py reviewboard/webapi/resources/review_request_last_update.py reviewboard/webapi/resources/user.py reviewboard/webapi/resources/base_diff_comment.py