Summary

Add and modernize documentation throughout WebAPIResource.

Review Request #13277 — Created Sept. 19, 2023 and submitted Sept. 25, 2023, 2:53 p.m.

Information

Owner

chipx86

Repository

Djblets

Branch

release-4.x

Bugs

Depends On

Reviewers

Groups

djblets

People

Description

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.

Testing Done

Unit tests pass.

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

Commits

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

Summary

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

Issues

Description	From	Last Updated
Typo in summary: documnentation	david	Sept. 25, 2023, 1:03 p.m.
SyntaxError: invalid syntax Column: 9 Error code: E999	reviewbot	Sept. 19, 2023, 12:06 a.m.
Can get rid of "Return" and just say "The plural name ..." like you did with the other docs.	maubin	Sept. 25, 2023, 1:03 p.m.
While you're here could you get rid of "Returns".	maubin	Sept. 25, 2023, 1:03 p.m.
While you're here could you get rid of "Returns".	maubin	Sept. 25, 2023, 1:04 p.m.
This should be removed, there is no specific object for list resources.	maubin	Sept. 25, 2023, 1:05 p.m.
This should say HTTP DELETE instead of POST.	maubin	Sept. 25, 2023, 1:05 p.m.
This should be "name" instead of "name_plural".	maubin	Sept. 25, 2023, 1:06 p.m.
Missing a leading underscore in the method name.	maubin	Sept. 25, 2023, 2:05 p.m.
Remove this line.	maubin	Sept. 25, 2023, 1:06 p.m.
Not sure if the word "included" should be here. Maybe this was meant to say "if included"?	maubin	Sept. 25, 2023, 1:06 p.m.
"optional" was written twice.	maubin	Sept. 25, 2023, 1:06 p.m.

flake8 failed.

JSHint passed.

flake8

djblets/webapi/resources/base.py (Diff revision 1)
Show all issues
```
SyntaxError: invalid syntax

Column: 9
Error code: E999
```

Change Summary:

ad Fixed a missing line from a bad git add -p.

Commits:

	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.	5868a895fc8610ebcc7d98403a235129a52e4514
	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.	e0cfc7603aa26ad4c71df269b9d6043f31851754

Diff:

Revision 2 (+1684 -216)

Show changes

djblets/webapi/resources/base.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

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

Show all issues
```
Typo in summary: documnentation
```

chipx86 Sept. 25, 2023, 1:08 p.m.

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

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.

djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
While you're here could you get rid of "Returns".
```
djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
While you're here could you get rid of "Returns".
```

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

Show all issues

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

djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
This should say HTTP DELETE instead of POST.
```
djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
This should be "name" instead of "name_plural".
```
djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
Remove this line.
```

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

djblets/webapi/resources/base.py (Diff revision 2)
Show all issues
```
"optional" was written twice.
```

Change Summary:

Fixed typos and all reported issues in the docs.

Summary:

-	Add and modernize documnentation throughout WebAPIResource.
+	Add and modernize documentation throughout WebAPIResource.

Commits:

	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.	e0cfc7603aa26ad4c71df269b9d6043f31851754
	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.	76f05439f5375c0406eb404798e1e8383e03fd95

Diff:

Revision 3 (+1682 -220)

Show changes

djblets/webapi/resources/base.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

djblets/webapi/resources/base.py (Diff revisions 2 - 3)
Show all issues
```
Missing a leading underscore in the method name.
```

Change Summary:

Fixed a missing _ in a method name reference.

Commits:

	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.	76f05439f5375c0406eb404798e1e8383e03fd95
	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

Diff:

Revision 4 (+1682 -220)

Show changes

djblets/webapi/resources/base.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Status: Closed (submitted)

Change Summary:

Pushed to release-4.x (6782524)