django-tasks icon indicating copy to clipboard operation
django-tasks copied to clipboard

Add docstring to `Task`

Open MarkoM-dot opened this issue 6 months ago • 1 comments

Hi!

The task class has multiple docstrings and perhaps there is a good reason for it but I cannot think of any. But there are a few undesirable consequences. Below I have the output of the __doc__ and the help command that do not look like documentation. Also, any docstring documentation generation would read this value and I am reasonably sure you'd rather the comments you've written show up here.

>>> Task.__doc__
"Task(priority: int, func: Callable[~P, ~T], backend: str, queue_name: str = 'default', run_after: Optional[datetime.datetime] = None, enqueue_on_commit: Optional[bool] = None)"
help(Task)

Help on class Task in module django_tasks.task:

class Task(typing.Generic)
 |  Task(priority: int, func: Callable[~P, ~T], backend: str, queue_name: str = 'default', run_after: Optional[datetime.datetime] = N
one, enqueue_on_commit: Optional[bool] = None) -> None
 |
 |  Task(priority: int, func: Callable[~P, ~T], backend: str, queue_name: str = 'default', run_after: Optional[datetime.datetime] = N
one, enqueue_on_commit: Optional[bool] = None)
 |
 |  Method resolution order:
 |      Task
 |      typing.Generic
 |      builtins.object
 |
 |  Methods defined here:

Let me know if you'd like to have this fixed. I don't mind contributing.

MarkoM-dot avatar May 16 '25 19:05 MarkoM-dot

It sounds like the main issue you mention is that the Task class itself doesn't have a docstring. I don't see that it necessarily needs one - I've mostly added them to methods to make it clear what they do both for users and people reading the implementation. The classes themselves don't really need them, but if you want to write a good one I definitely won't say no to merging it.

RealOrangeOne avatar May 17 '25 15:05 RealOrangeOne