doc: add notes to Timer.mo (#683)

This brings the notes in line with what the Motoko `docs/md/Timer.md`
is.

Basically also reverts #682.

Plus a few tweaks.

src/Debug.mo

@@ -11,7 +11,7 @@ module {
   ///
   /// NOTE: When running on an ICP network, all output is written to the [canister log](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/logs) with the exclusion of any output
   /// produced during the execution of non-replicated queries and composite queries.
-  /// In other environments, like the interpreter and stand-alone wasm engines, the output is written to standard out.  
+  /// In other environments, like the interpreter and stand-alone wasm engines, the output is written to standard out.
   ///
   /// ```motoko include=import
   /// Debug.print "Hello New World!";

src/ExperimentalInternetComputer.mo

@@ -85,7 +85,6 @@ module {
   /// Returns the time (in nanoseconds from the epoch start) by when the update message should
   /// reply to the best effort message so that it can be received by the requesting canister.
   /// Queries and non-best-effort update messages return zero.
-  ///
   public func replyDeadline() : Nat = Prim.nat64ToNat(Prim.replyDeadline());
 
 }

src/Timer.mo

@@ -1,10 +1,26 @@
-/// Timers for one-off or periodic tasks.
+/// Timers for one-off or periodic tasks. Applicable as part of the default mechanism.
 ///
 /// Note: If `moc` is invoked with `-no-timer`, the importing will fail.
+///
 /// 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 heatbeat mechanism should be considered.
-
+///       canister wake-ups the heartbeat mechanism should be considered.
+///
+/// Note: The functionality described below is enabled only when the actor does not override it by declaring an explicit `system func timer`.
+///
+/// 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.
+///
+/// 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
 import { setTimer = setTimerNano; cancelTimer = cancel } = "mo:⛔";
 import { fromIntWrap } = "Nat64";
 
@@ -21,9 +37,6 @@ module {
   /// Installs a one-off timer that upon expiration after given duration `d`
   /// executes the future `job()`.
   ///
-  /// Note: Since `job` can be called more than once (under rare circumstances),
-  ///       it should not possess side-effects.
-  ///
   /// ```motoko no-repl
   /// let now = Time.now();
   /// let thirtyMinutes = 1_000_000_000 * 60 * 30;
@@ -40,8 +53,6 @@ module {
   /// executes the future `job()` and reinserts itself for another expiration.
   ///
   /// Note: A duration of 0 will only expire once.
-  /// Note: Since `job` can be called more than once (under rare circumstances),
-  ///       it should not possess side-effects.
   ///
   /// ```motoko no-repl
   /// func checkAndWaterPlants() : async () {