Summary

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

Review Request #10465 — Created May 17, 2019 and updated May 20, 2019, 6:38 p.m.

Information

Owner

chipx86

Repository

RBTools

Branch

master

Bugs

Depends On

Reviewers

Groups

rbtools

People

Description

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.

Testing Done

Posted this change successfully.

Unit tests pass.

Commits

Summary	ID
Modernize documentation and fix old warts in some of the API code. 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`.	78fd5cdd056246106025b03ee01e8c500e00455c

Summary

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

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`.

78fd5cdd056246106025b03ee01e8c500e00455c

Issues

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 …	david	Sept. 24, 2019, 2:03 p.m.
I don't think "Two Factor Auth" needs to be title cased	david	Sept. 24, 2019, 2:03 p.m.
And here.	david	Sept. 24, 2019, 2:03 p.m.

flake8 passed.

JSHint passed.

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

Show all issues

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."

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

Show all issues

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

rbtools/api/request.py (Diff revision 1)
Show all issues
```
And here.
```