Modernize documentation and fix old warts in some of the API code.

Review Request #10465 — Created May 17, 2019 and updated

chipx86
RBTools
master
rbtools

The API code was written before our current documentation standards, and
largely lacked any documentation. Some of the documentation we had was
incomplete or misleading. This made it a bit hard to reason about this
part of the codebase and make changes to it, and made it hard to consume
without reading through a lot of complex code.

This change fleshes out documentation for several of the major
components in the communication layers of the API, bringing these parts
up-to-date with our standards.

To help with readability, it also fixes up a few function signatures in
places, marks a few internal attributes in ReviewBoardServer as
private, and removes some unneeded attributes in
ReviewBoardHTTPPasswordMgr.

Posted this change successfully.

Unit tests pass.

Summary
Modernize documentation and fix old warts in some of the API code.
Description From Last Updated

This first paragraph is pretty clunky. How about "If authenticating with Review Board and an :py:attr:auth_callback is provided to the ...

daviddavid

I don't think "Two Factor Auth" needs to be title cased

daviddavid

And here.

daviddavid
Checks run (2 succeeded)
flake8 passed.
JSHint passed.
david
  1. 
      
  2. rbtools/api/request.py (Diff revision 1)
     
     
     
     

    This first paragraph is pretty clunky. How about "If authenticating with Review Board and an :py:attr:auth_callback is provided to the password manager, it will always be called. This allows the callback to provide a new username and password, which will then be returned."

  3. rbtools/api/request.py (Diff revision 1)
     
     

    I don't think "Two Factor Auth" needs to be title cased

  4. rbtools/api/request.py (Diff revision 1)
     
     

    And here.

  5. 
      
Loading...