bpo-41710: Document _PyTime_t API in pytime.h (GH-28647)

Author: vstinner

Include/cpython/pytime.h

@@ -1,3 +1,44 @@
+// The _PyTime_t API is written to use timestamp and timeout values stored in
+// various formats and to read clocks.
+//
+// The _PyTime_t type is an integer to support directly common arithmetic
+// operations like t1 + t2.
+//
+// The _PyTime_t API supports a resolution of 1 nanosecond. The _PyTime_t type
+// is signed to support negative timestamps. The supported range is around
+// [-292.3 years; +292.3 years]. Using the Unix epoch (January 1st, 1970), the
+// supported date range is around [1677-09-21; 2262-04-11].
+//
+// Formats:
+//
+// * seconds
+// * seconds as a floating pointer number (C double)
+// * milliseconds (10^-3 seconds)
+// * microseconds (10^-6 seconds)
+// * 100 nanoseconds (10^-7 seconds)
+// * nanoseconds (10^-9 seconds)
+// * timeval structure, 1 microsecond resolution (10^-6 seconds)
+// * timespec structure, 1 nanosecond resolution (10^-9 seconds)
+//
+// Integer overflows are detected and raise OverflowError. Conversion to a
+// resolution worse than 1 nanosecond is rounded correctly with the requested
+// rounding mode. There are 4 rounding modes: floor (towards -inf), ceiling
+// (towards +inf), half even and up (away from zero).
+//
+// Some functions clamp the result in the range [_PyTime_MIN; _PyTime_MAX], so
+// the caller doesn't have to handle errors and doesn't need to hold the GIL.
+//
+// Clocks:
+//
+// * System clock
+// * Monotonic clock
+// * Performance counter
+//
+// Operations like (t * k / q) with integers are implemented in a way to reduce
+// the risk of integer overflow. Such operation is used to convert a clock
+// value expressed in ticks with a frequency to _PyTime_t, like
+// QueryPerformanceCounter() with QueryPerformanceFrequency().
+
 #ifndef Py_LIMITED_API
 #ifndef Py_PYTIME_H
 #define Py_PYTIME_H