Flesh out the documentation for ReviewRequestManager query functions.

Review Request #12340 — Created June 8, 2022 and submitted

Information

Review Board
release-5.0.x

Reviewers

The query functions in ReviewRequestManager are very old, and most
either lacked documentation or didn't meet current documentation
conventions.

As some work is being done in these functions, and given the importance
of these functions and their behavior, it's time to ensure they meet
documentation standards.

This updates the docstrings for all the query functions, making
behaviors and usage explicit.

No logic has changed.

Built the docs and checked through them. Didn't see anything
obvious or any build errors/warnings related to this file.

Summary ID
Flesh out the documentation for ReviewRequestManager query functions.
The query functions in `ReviewRequestManager` are very old, and most either lacked documentation or didn't meet current documentation conventions. As some work is being done in these functions, and given the importance of these functions and their behavior, it's time to ensure they meet documentation standards. This updates the docstrings for all the query functions, making behaviors and usage explicit. No logic has changed.
6cceba85a82c9c7c993c047240239e398f0a55f1
Description From Last Updated

Could shorten this to just "The User instance or username."

maubinmaubin

Change to "The User instance or username."

maubinmaubin

Can change this to "The query object." and move the information about the query into the description

maubinmaubin

Should we mention that if a local site is given, it is assumed that the user (if given) has access …

maubinmaubin

Add a Raises: section for the django.contrib.auth.models.User.DoesNotExist error that could happen in in self.get_to_or_from_user_query

maubinmaubin
maubin
  1. 
      
  2. reviewboard/reviews/managers.py (Diff revision 1)
     
     
    Show all issues

    Could shorten this to just "The User instance or username."

    1. Think I actually need to elaborate more. In the queries, there's a couple references to users. The viewing user and the owner. I'm going to change these to be explicit about what's expected where.

  3. reviewboard/reviews/managers.py (Diff revision 1)
     
     
    Show all issues

    Change to "The User instance or username."

    1. There's an example of one that differs in meaning from the previous.

  4. reviewboard/reviews/managers.py (Diff revision 1)
     
     
     
     
    Show all issues

    Can change this to "The query object." and move the information about the query into the description

  5. reviewboard/reviews/managers.py (Diff revision 1)
     
     
    Show all issues

    Should we mention that if a local site is given, it is assumed that the user (if given) has access to that local site (i.e. we don't check whether a user has access to that local site). If so we could include that here under the arg description (and every where else where a local_site arg is used) or maybe under the description for the method where you talk about filtering based on access

  6. reviewboard/reviews/managers.py (Diff revision 1)
     
     
    Show all issues

    Add a Raises: section for the django.contrib.auth.models.User.DoesNotExist error that could happen in in self.get_to_or_from_user_query

  7. 
      
chipx86
maubin
  1. Good call on being more explicit about the user args

  2. 
      
david
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-5.0.x (bbb7b44)