Update Timer doc comments (#685)

Adjusts the wording of the `Timer` documentation based on feedback. This
is intended as a starting point; please feel free to suggest additional
changes.

---------

Co-authored-by: Jessie Mongeon <[email protected]>
Co-authored-by: Gabor Greif <[email protected]>

src/Timer.mo

@@ -1,26 +1,25 @@
 /// Timers for one-off or periodic tasks. Applicable as part of the default mechanism.
+/// If `moc` is invoked with `-no-timer`, the importing will fail. Furthermore, if passed `--trap-on-call-error`, a congested canister send queue may prevent timer expirations to execute at runtime. It may also deactivate the global timer.
 ///
-/// Note: If `moc` is invoked with `-no-timer`, the importing will fail.
+/// The resolution of the timers is similar to the block rate,
+/// so durations should be chosen well above that. For frequent
+/// canister wake-ups, consider using the [heartbeat](https://internetcomputer.org/docs/current/motoko/main/writing-motoko/heartbeats) mechanism; however, when possible, canisters should prefer timers.
 ///
-/// Note: The resolution of the timers is in the order of the block rate,
-///       so durations should be chosen well above that. For frequent
-///       canister wake-ups the heartbeat mechanism should be considered.
+/// The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`.
 ///
-/// Note: The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`.
+/// Timers are _not_ persisted across upgrades. One possible strategy
+/// to re-establish timers after an upgrade is to use stable variables
+/// in the `post_upgrade` hook and distill necessary timer information
+/// from there.
 ///
-/// Note: Timers are _not_ persisted across upgrades. One possible strategy
-///       to re-establish timers after an upgrade is to walk stable variables
-///       in the `post_upgrade` hook and distill necessary timer information
-///       from there.
+/// Using timers for security (e.g., access control) is strongly discouraged.
+/// Make sure to inform yourself about state-of-the-art dapp security.
+/// If you must use timers for security controls, be sure
+/// to consider reentrancy issues as well as the vanishing of timers on upgrades
+/// and reinstalls.
 ///
-/// Note: Basing security (e.g. access control) on timers is almost always
-///       the wrong choice. Be sure to inform yourself about state-of-the art
-///       dApp security. If you _must use_ timers for security controls, be sure
-///       to consider reentrancy issues, and the vanishing of timers on upgrades
-///       and reinstalls.
-///
-/// Note: For further usage information for timers on the IC please consult
-///       https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations
+/// For further usage information for timers on the IC, please consult
+/// [the documentation](https://internetcomputer.org/docs/current/developer-docs/backend/periodic-tasks#timers-library-limitations).
 import { setTimer = setTimerNano; cancelTimer = cancel } = "mo:⛔";
 import { fromIntWrap } = "Nat64";
 
@@ -68,8 +67,8 @@ module {
   /// and not recognised `id`s nothing happens.
   ///
   /// ```motoko no-repl
-  /// func deleteAppt(appt : Appointment) {
-  ///   cancelTimer (appt.reminder);
+  /// func deleteAppointment(appointment : Appointment) {
+  ///   cancelTimer (appointment.reminder);
   ///   // ...
   /// };
   /// ```