Improve docs around subtracting times (#6152)

The output can be surprising - better provide examples.

1 files changed, 12 insertions, 0 deletions

diff --git a/lib/pure/times.nim b/lib/pure/times.nim
index c2809acf7..03054e2d9 100644
--- a/lib/pure/times.nim
+++ b/lib/pure/times.nim
@@ -222,6 +222,12 @@ proc toSeconds*(time: Time): float {.tags: [], raises: [], benign.}
 proc `-`*(a, b: Time): int64 {.
   rtl, extern: "ntDiffTime", tags: [], raises: [], noSideEffect, benign.}
   ## computes the difference of two calendar times. Result is in seconds.
+  ## .. code-block:: nim 
+  ## 
+  ##     let a = fromSeconds(1_000_000_000)
+  ##     let b = fromSeconds(1_500_000_000)
+  ##     echo initInterval(seconds=int(b - a)) 
+  ##     # (milliseconds: 0, seconds: 20, minutes: 53, hours: 0, days: 5787, months: 0, years: 0) 
 
 proc `<`*(a, b: Time): bool {.
   rtl, extern: "ntLtTime", tags: [], raises: [], noSideEffect.} =
@@ -318,6 +324,12 @@ proc `-`*(ti: TimeInterval): TimeInterval =
 
 proc `-`*(ti1, ti2: TimeInterval): TimeInterval =
   ## Subtracts TimeInterval ``ti1`` from ``ti2``.
+  ## .. code-block:: nim 
+  ## 
+  ##     let a = fromSeconds(1_000_000_000) 
+  ##     let b = fromSeconds(1_500_000_000) 
+  ##     echo b.toTimeInterval - a.toTimeInterval 
+  ##     # (milliseconds: 0, seconds: -40, minutes: -6, hours: 1, days: -2, months: -2, years: 16)
   result = ti1 + (-ti2)
 
 proc isLeapYear*(year: int): bool =