Summary

Add a @webapi_docs decorator to store docs on the function.

Review Request #14046 — Created July 17, 2024 and submitted April 30, 2025, 9:31 a.m.

Information

Owner

david

Repository

Djblets

Branch

release-6.x

Bugs

Depends On

Reviewers

Groups

djblets

People

Description

This change adds a new decorator for us to use for attaching

public-facing documentation to HTTP methods, rather than putting it into

the docstring. This will let us have internal codebase docs in the docstring

instead, which is much more appropriate.

Testing Done

Used along with a change to our webapidocs Sphinx extension to pull this
data out.

Commits

Summary	ID
Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	508cc109ab61c2198d80f6f3e225d2998ae4b37e

Summary

Add a @webapi_docs decorator to store docs on the function.

This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.

508cc109ab61c2198d80f6f3e225d2998ae4b37e

Issues

Description	From	Last Updated
Can you add a unit test in test_decorators.py for this, and make sure that other state from other decorators (including …	chipx86	Sept. 10, 2024, 8:23 a.m.
Looked up how we handle type-safety decorators elsewhere. We use this pattern: _FuncT = TypeVar('_FuncT', bound=Callable[..., WebAPIResourceHandlerResult]) def my_decorator( params, …	chipx86	March 17, 2025, 8:32 a.m.
'djblets.webapi.resources.base.WebAPIResourceHandlerResult' imported but unused Column: 5 Error code: F401	reviewbot	March 17, 2025, 8:34 a.m.
at least two spaces before inline comment Column: 34 Error code: E261	reviewbot	March 17, 2025, 8:34 a.m.
line too long (80 > 79 characters) Column: 80 Error code: E501	reviewbot	March 17, 2025, 8:37 a.m.
We can put these in a TYPE_CHECKING.	chipx86	April 30, 2025, 9:30 a.m.

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

The issue has been resolved. Show all issues

Can you add a unit test in test_decorators.py for this, and make sure that other state from other decorators (including name, type hints, etc.) are retained?

Change Summary:


Add a unit test for state preservation.
Clean up test_decorators a bit and update for modern world.

Commits:

	Summary	ID
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	ab2fbc43320257bdf92d0b34edbe5e1242150c85
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	099af51e231f815a6a1a877c200ceef753422b24

Diff:

Revision 2 (+262 -186)

Show changes

	djblets/webapi/decorators.py
	djblets/webapi/tests/test_decorators.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Code looks good, but all the cleanup changes makes it really hard to focus on what's relevant to this new unit test, and makes for more difficult code archaeology later. Possible to split this out?

Change Summary:

Split out test cleanup changes.

Commits:

	Summary	ID
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	099af51e231f815a6a1a877c200ceef753422b24
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	07ea9819d74c9280b46db50e336c0d144a2083b3

Diff:

Revision 3 (+142 -18)

Show changes

	djblets/webapi/decorators.py
	djblets/webapi/tests/test_decorators.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

djblets/webapi/decorators.py (Diff revision 3)

The issue has been resolved. Show all issues

Looked up how we handle type-safety decorators elsewhere. We use this pattern:


_FuncT = TypeVar('_FuncT', bound=Callable[..., WebAPIResourceHandlerResult])


def my_decorator(
    params,
) -> Callable[[_FuncT], _FuncT]:
    def _dec(
        func: _FuncT,
    ) -> _FuncT:
        return ...

    return _dec


That'll keep the function signature passed all the way through.

david March 17, 2025, 7:49 a.m.

Forgot how old this change was. There's a much better way now, with ParamSpec. I'll update this to us that.

Commits:

	Summary	ID
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	07ea9819d74c9280b46db50e336c0d144a2083b3
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	065a0e9933773e598016c944530249ee14de5cf6

Diff:

Revision 4 (+158 -18)

Show changes

	djblets/webapi/decorators.py
	djblets/webapi/tests/test_decorators.py

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

djblets/webapi/decorators.py (Diff revision 4)

The issue has been dropped. Show all issues

'djblets.webapi.resources.base.WebAPIResourceHandlerResult' imported but unused

Column: 5
Error code: F401

djblets/webapi/decorators.py (Diff revision 4)
The issue has been dropped. Show all issues
```
at least two spaces before inline comment

Column: 34
Error code: E261
```

Commits:

	Summary	ID
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	065a0e9933773e598016c944530249ee14de5cf6
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	5fbccfd8d8802402f4f2a4a6ecae1dfa444f74b7

Diff:

Revision 5 (+152 -18)

Show changes

	djblets/webapi/decorators.py
	djblets/webapi/tests/test_decorators.py

Checks run (1 failed, 1 succeeded)

flake8 failed.

JSHint passed.

flake8

djblets/webapi/decorators.py (Diff revision 5)
The issue has been dropped. Show all issues
```
line too long (80 > 79 characters)

Column: 80
Error code: E501
```

Commits:

	Summary	ID
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	5fbccfd8d8802402f4f2a4a6ecae1dfa444f74b7
	Add a @webapi_docs decorator to store docs on the function. This change adds a new decorator for us to use for attaching public-facing documentation to HTTP methods, rather than putting it into the docstring. This will let us have internal codebase docs in the docstring instead, which is much more appropriate. Testing Done: Used along with a change to our webapidocs Sphinx extension to pull this data out.	508cc109ab61c2198d80f6f3e225d2998ae4b37e

Diff:

Revision 6 (+152 -18)

Show changes

	djblets/webapi/decorators.py
	djblets/webapi/tests/test_decorators.py

Checks run (2 succeeded)

flake8 passed.

JSHint passed.

Ship it!

```
Ship It!
```

Ship it!

djblets/webapi/decorators.py (Diff revision 6)
The issue has been resolved. Show all issues
```
We can put these in a TYPE_CHECKING.
```

Status:: Completed
Change Summary:: Pushed to release-6.x (9459f5a)