From 97050569c9ece825d02a2e037f93597689f07049 Mon Sep 17 00:00:00 2001
From: Carlos Alexandro Becker <caarlos0@users.noreply.github.com>
Date: Sun, 29 May 2022 21:40:57 -0300
Subject: [PATCH] docs: improve godoc on tick and every (#320)

* docs: improve godoc on tick and every

Signed-off-by: Carlos A Becker <caarlos0@users.noreply.github.com>

* docs: small improvements

Signed-off-by: Carlos A Becker <caarlos0@users.noreply.github.com>

* docs: add loop examples for Tick/Every in GoDocs

* docs: small wording adjustments

* docs: small copy edits

Co-authored-by: Christian Rocha <christian@rocha.is>
---
 commands.go | 64 +++++++++++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 60 insertions(+), 4 deletions(-)

diff --git a/commands.go b/commands.go
index 8aeab21..99007b2 100644
--- a/commands.go
+++ b/commands.go
@@ -24,6 +24,35 @@ import (
 //   cmd := Every(time.Second, func(t time.Time) Msg {
 //      return TickMsg(t)
 //   })
+//
+// Beginners' note: Every sends a single message and won't automatically
+// dispatch messages at an interval. To do that, you'll want to return another
+// Every command after receiving your tick message. For example:
+//
+//   type TickMsg time.Time
+//
+//   // Send a message every second.
+//   func tickEvery() Cmd {
+//       return Every(time.Second, func(t time.Time) Msg {
+//           return TickMsg(t)
+//       })
+//   }
+//
+//   func (m model) Init() Cmd {
+//       // Start ticking.
+//       return tickEvery()
+//   }
+//
+//   func (m model) Update(msg Msg) (Model, Cmd) {
+//       switch msg.(type) {
+//       case TickMsg:
+//           // Return your Every command again to loop.
+//           return m, tickEvery()
+//       }
+//       return m, nil
+//   }
+//
+// Every is analogous to Tick in the Elm Architecture.
 func Every(duration time.Duration, fn func(time.Time) Msg) Cmd {
 	return func() Msg {
 		n := time.Now()
@@ -45,6 +74,33 @@ func Every(duration time.Duration, fn func(time.Time) Msg) Cmd {
 //   cmd := Tick(time.Second, func(t time.Time) Msg {
 //      return TickMsg(t)
 //   })
+//
+// Beginners' note: Tick sends a single message and won't automatically
+// dispatch messages at an interval. To do that, you'll want to return another
+// Tick command after receiving your tick message. For example:
+//
+//   type TickMsg time.Time
+//
+//   func doTick() Cmd {
+//       return Tick(time.Second, func(t time.Time) Msg {
+//           return TickMsg(t)
+//       })
+//   }
+//
+//   func (m model) Init() Cmd {
+//       // Start ticking.
+//       return doTick()
+//   }
+//
+//   func (m model) Update(msg Msg) (Model, Cmd) {
+//       switch msg.(type) {
+//       case TickMsg:
+//           // Return your Tick command again to loop.
+//           return m, doTick()
+//       }
+//       return m, nil
+//   }
+//
 func Tick(d time.Duration, fn func(time.Time) Msg) Cmd {
 	return func() Msg {
 		t := time.NewTimer(d)
@@ -57,10 +113,10 @@ func Tick(d time.Duration, fn func(time.Time) Msg) Cmd {
 // The Msg returned is the first non-nil message returned by a Cmd.
 //
 //   func saveStateCmd() Msg {
-//   	if err := save(); err != nil {
-//    		return errMsg{err}
-//    	}
-//   	return nil
+//      if err := save(); err != nil {
+//          return errMsg{err}
+//      }
+//      return nil
 //   }
 //
 //   cmd := Sequentially(saveStateCmd, Quit)