Fix and improve documentation throughout the API.

Review Request #8774 — Created Feb. 21, 2017 and submitted

Information

Review Board
release-2.5.x
76093d0...

Reviewers

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

reviewbotreviewbot
reviewbot
  1. 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
    
    
  2.  'WebAPIResource' imported but unused
    
  3. 
      
reviewbot
  1. 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
    
    
  2. 
      
chipx86
reviewbot
  1. 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
    
    
  2. 
      
reviewbot
  1. 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
    
    
  2. 
      
david
  1. Ship It!
  2. 
      
chipx86
Review request changed

Status: Closed (submitted)

Change Summary:

Pushed to release-2.5.x (ad24846)
Loading...