Improved documentation of data structures

Parameters were changed to variables in classes that end users aren't supposed to instantiate directly.

1 files changed, 69 insertions, 61 deletions

diff --git a/src/apscheduler/_structures.py b/src/apscheduler/_structures.py
index ba3359b..0a959e4 100644
--- a/src/apscheduler/_structures.py
+++ b/src/apscheduler/_structures.py
@@ -1,8 +1,9 @@
 from __future__ import annotations
 
+from collections.abc import Callable
 from datetime import datetime, timedelta, timezone
 from functools import partial
-from typing import TYPE_CHECKING, Any, Callable
+from typing import TYPE_CHECKING, Any
 from uuid import UUID, uuid4
 
 import attrs
@@ -30,12 +31,14 @@ class Task:
     """
     Represents a callable and its surrounding configuration parameters.
 
-    :param id: the unique identifier of this task
-    :param func: the callable that is called when this task is run
-    :param max_running_jobs: maximum number of instances of this task that are allowed
-        to run concurrently
-    :param misfire_grace_time: maximum number of seconds the run time of jobs created
-        for this task are allowed to be late, compared to the scheduled run time
+    :var str id: the unique identifier of this task
+    :var ~collections.abc.Callable func: the callable that is called when this task is
+        run
+    :var int | None max_running_jobs: maximum number of instances of this task that are
+        allowed to run concurrently
+    :var ~datetime.timedelta | None misfire_grace_time: maximum number of seconds the
+        run time of jobs created for this task are allowed to be late, compared to the
+        scheduled run time
     """
 
     id: str
@@ -66,26 +69,28 @@ class Schedule:
     """
     Represents a schedule on which a task will be run.
 
-    :param id: the unique identifier of this schedule
-    :param task_id: unique identifier of the task to be run on this schedule
-    :param args: positional arguments to pass to the task callable
-    :param kwargs: keyword arguments to pass to the task callable
-    :param coalesce: determines what to do when processing the schedule if multiple
-        fire times have become due for this schedule since the last processing
-    :param misfire_grace_time: maximum number of seconds the scheduled job's actual
-        run time is allowed to be late, compared to the scheduled run time
-    :param max_jitter: maximum number of seconds to randomly add to the scheduled
-        time for each job created from this schedule
-    :param tags: strings that can be used to categorize and filter the schedule and
-        its derivative jobs
-    :param conflict_policy: determines what to do if a schedule with the same ID
-        already exists in the data store
-    :param next_fire_time: the next time the task will be run
-    :param last_fire_time: the last time the task was scheduled to run
-    :param acquired_by: ID of the scheduler that has acquired this schedule for
+    :var str id: the unique identifier of this schedule
+    :var str task_id: unique identifier of the task to be run on this schedule
+    :var tuple args: positional arguments to pass to the task callable
+    :var dict[str, Any] kwargs: keyword arguments to pass to the task callable
+    :var CoalescePolicy coalesce: determines what to do when processing the schedule if
+        multiple fire times have become due for this schedule since the last processing
+    :var ~datetime.timedelta | None misfire_grace_time: maximum number of seconds the
+        scheduled job's actual run time is allowed to be late, compared to the scheduled
+        run time
+    :var ~datetime.timedelta | None max_jitter: maximum number of seconds to randomly
+        add to the scheduled time for each job created from this schedule
+    :var frozenset[str] tags: strings that can be used to categorize and filter the
+        schedule and its derivative jobs
+    :var ConflictPolicy conflict_policy: determines what to do if a schedule with the
+        same ID already exists in the data store
+    :var ~datetime.datetime next_fire_time: the next time the task will be run
+    :var ~datetime.datetime | None last_fire_time: the last time the task was scheduled
+        to run
+    :var str | None acquired_by: ID of the scheduler that has acquired this schedule for
         processing
-    :param acquired_until: the time after which other schedulers are free to acquire the
-        schedule for processing even if it is still marked as acquired
+    :var str | None acquired_until: the time after which other schedulers are free to
+        acquire the schedule for processing even if it is still marked as acquired
     """
 
     id: str
@@ -146,27 +151,28 @@ class Job:
     """
     Represents a queued request to run a task.
 
-    :param id: autogenerated unique identifier of the job
-    :param task_id: unique identifier of the task to be run
-    :param args: positional arguments to pass to the task callable
-    :param kwargs: keyword arguments to pass to the task callable
-    :param schedule_id: unique identifier of the associated schedule
+    :var ~uuid.UUID id: autogenerated unique identifier of the job
+    :var str task_id: unique identifier of the task to be run
+    :var tuple args: positional arguments to pass to the task callable
+    :var dict[str, Any] kwargs: keyword arguments to pass to the task callable
+    :var str schedule_id: unique identifier of the associated schedule
         (if the job was derived from a schedule)
-    :param scheduled_fire_time: the time the job was scheduled to run at
-        (if the job was derived from a schedule; includes jitter)
-    :param jitter: the time that was randomly added to the calculated scheduled run time
-        (if the job was derived from a schedule)
-    :param start_deadline: if the job is started in the worker after this time, it is
-        considered to be misfired and will be aborted
-    :param result_expiration_time: minimum amount of time to keep the result available
-        for fetching in the data store
-    :param tags: strings that can be used to categorize and filter the job
-    :param created_at: the time at which the job was created
-    :param started_at: the time at which the execution of the job was started
-    :param acquired_by: the unique identifier of the worker that has acquired the job
-        for execution
-    :param acquired_until: the time after which other workers are free to acquire the
-        job for processing even if it is still marked as acquired
+    :var ~datetime.datetime | None scheduled_fire_time: the time the job was scheduled
+        to run at (if the job was derived from a schedule; includes jitter)
+    :var ~datetime.timedelta | None jitter: the time that was randomly added to the
+        calculated scheduled run time (if the job was derived from a schedule)
+    :var ~datetime.datetime | None start_deadline: if the job is started in the worker
+        after this time, it is considered to be misfired and will be aborted
+    :var ~datetime.timedelta result_expiration_time: minimum amount of time to keep the
+        result available for fetching in the data store
+    :var frozenset[str] tags: strings that can be used to categorize and filter the job
+    :var ~datetime.datetime created_at: the time at which the job was created
+    :var ~datetime.datetime | None started_at: the time at which the execution of the
+        job was started
+    :var str | None acquired_by: the unique identifier of the worker that has acquired
+        the job for execution
+    :var str | None acquired_until: the time after which other workers are free to
+        acquire the job for processing even if it is still marked as acquired
     """
 
     id: UUID = attrs.field(factory=uuid4)
@@ -229,15 +235,17 @@ class JobInfo:
     This information is available in the thread or task where a job is currently being
     run, available from :data:`~apscheduler.current_job`.
 
-    :param job_id: the unique identifier of the job
-    :param task_id: the unique identifier of the task that is being run
-    :param schedule_id: the unique identifier of the schedule that the job was derived
-        from (if any)
-    :param jitter: the time that was randomly added to the calculated scheduled run time
-        (if the job was derived from a schedule)
-    :param start_deadline: if the job is started in the worker after this time, it is
-        considered to be misfired and will be aborted
-    :param tags: strings that can be used to categorize and filter the job
+    :var ~uuid.UUID job_id: the unique identifier of the job
+    :var str task_id: the unique identifier of the task that is being run
+    :var str | None schedule_id: the unique identifier of the schedule that the job was
+        derived from (if any)
+    :var ~datetime.datetime | None scheduled_fire_time: the time the job was scheduled
+        to run at (if the job was derived from a schedule; includes jitter)
+    :var ~datetime.timedelta jitter: the time that was randomly added to the calculated
+        scheduled run time (if the job was derived from a schedule)
+    :var ~datetime.datetime | None start_deadline: if the job is started in the worker
+        after this time, it is considered to be misfired and will be aborted
+    :var frozenset[str] tags: strings that can be used to categorize and filter the job
     """
 
     job_id: UUID
@@ -266,12 +274,12 @@ class JobResult:
     """
     Represents the result of running a job.
 
-    :param job_id: the unique identifier of the job
-    :param outcome: indicates how the job ended
-    :param finished_at: the time when the job ended
-    :param exception: the exception object if the job ended due to an exception being
-        raised
-    :param return_value: the return value from the task function (if the job ran to
+    :var ~uuid.UUID job_id: the unique identifier of the job
+    :var JobOutcome outcome: indicates how the job ended
+    :var ~datetime.datetime finished_at: the time when the job ended
+    :var BaseException | None exception: the exception object if the job ended due to an
+        exception being raised
+    :var return_value: the return value from the task function (if the job ran to
         completion successfully)
     """