Add and modernize documentation throughout WebAPIResource.

Review Request #13277 — Created Sept. 19, 2023 and submitted

Information

Djblets
release-4.x

Reviewers

WebAPIResource is a very old and complex part of our codebase, and
lacked any form of modern documentation. This made it more difficult to
iterate on, and with some upcoming work planned for this, it was time to
address this problem.

This change adds documentation to all the methods in the class, and sets
the stage for those upcoming changes.

Unit tests pass.

Built the docs. Verified there were no new errors in this module.

Summary ID
Add and modernize documnentation throughout WebAPIResource.
`WebAPIResource` is a very old and complex part of our codebase, and lacked any form of modern documentation. This made it more difficult to iterate on, and with some upcoming work planned for this, it was time to address this problem. This change adds documentation to all the methods in the class, and sets the stage for those upcoming changes.
aaa6b7f59ff7249c35e60a2fbf893fadb705e6fb
Description From Last Updated

Typo in summary: documnentation

daviddavid

SyntaxError: invalid syntax Column: 9 Error code: E999

reviewbotreviewbot

Can get rid of "Return" and just say "The plural name ..." like you did with the other docs.

maubinmaubin

While you're here could you get rid of "Returns".

maubinmaubin

While you're here could you get rid of "Returns".

maubinmaubin

This should be removed, there is no specific object for list resources.

maubinmaubin

This should say HTTP DELETE instead of POST.

maubinmaubin

This should be "name" instead of "name_plural".

maubinmaubin

Missing a leading underscore in the method name.

maubinmaubin

Remove this line.

maubinmaubin

Not sure if the word "included" should be here. Maybe this was meant to say "if included"?

maubinmaubin

"optional" was written twice.

maubinmaubin
Checks run (1 failed, 1 succeeded)
flake8 failed.
JSHint passed.

flake8

chipx86
david
  1. I admit I skimmed a bit but by and large this looks great. Thanks!

  2. Show all issues

    Typo in summary: documnentation

  3. 
      
maubin
  1. 
      
    1. Thanks! Good catches. I'm off my game lately.

  2. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    Can get rid of "Return" and just say "The plural name ..." like you did with the other docs.

  3. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    While you're here could you get rid of "Returns".

  4. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    While you're here could you get rid of "Returns".

  5. djblets/webapi/resources/base.py (Diff revision 2)
     
     
     
    Show all issues

    This should be removed, there is no specific object for list resources.

  6. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    This should say HTTP DELETE instead of POST.

  7. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    This should be "name" instead of "name_plural".

  8. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    Remove this line.

  9. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    Not sure if the word "included" should be here. Maybe this was meant to say "if included"?

  10. djblets/webapi/resources/base.py (Diff revision 2)
     
     
    Show all issues

    "optional" was written twice.

  11. 
      
chipx86
maubin
  1. 
      
  2. djblets/webapi/resources/base.py (Diff revisions 2 - 3)
     
     
    Show all issues

    Missing a leading underscore in the method name.

  3. 
      
chipx86
maubin
  1. Ship It!
  2. 
      
chipx86
Review request changed
Status:
Completed
Change Summary:
Pushed to release-4.x (6782524)