Improve the connectivity check state machine docs

lib/vintage_net/connectivity/check_logic.ex

@@ -3,8 +3,14 @@ defmodule VintageNet.Connectivity.CheckLogic do
   Core logic for determining internet connectivity based on check results
 
   This module is meant to be used by `InternetChecker` and others for
-  determining when to run checks and how many failures should change
-  the network interface's state.
+  determining when to run checks and how many failures should change the
+  network interface's state.
+
+  It implements a state machine that figures out what the connectivity status
+  is based on internet-connectivity check successes and fails. It also returns
+  how long to wait between checks.
+
+  [![](https://mermaid.ink/img/eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyIFxuICAgIGRpcmVjdGlvbiBMUlxuICAgIFsqXS0tPmludGVybmV0IDogaW5pdCBcblxuICAgIHN0YXRlIGNvbm5lY3RlZCB7XG4gICAgICBpbnRlcm5ldC0tPmxhbiA6IG1heCBmYWlsdXJlc1xuICAgICAgbGFuLS0-aW50ZXJuZXQgOiBjaGVjayBzdWNjZWVkZWRcbiAgICB9XG4gICAgY29ubmVjdGVkLS0-ZGlzY29ubmVjdGVkIDogaWZkb3duXG4gICAgZGlzY29ubmVjdGVkLS0-bGFuIDogaWZ1cFxuICAgIFxuIiwibWVybWFpZCI6eyJ0aGVtZSI6ImRlZmF1bHQifSwidXBkYXRlRWRpdG9yIjpmYWxzZSwiYXV0b1N5bmMiOnRydWUsInVwZGF0ZURpYWdyYW0iOmZhbHNlfQ)](https://mermaid-js.github.io/mermaid-live-editor/edit#eyJjb2RlIjoic3RhdGVEaWFncmFtLXYyIFxuICAgIGRpcmVjdGlvbiBMUlxuICAgIFsqXS0tPmludGVybmV0IDogaW5pdCBcblxuICAgIHN0YXRlIGNvbm5lY3RlZCB7XG4gICAgICBpbnRlcm5ldC0tPmxhbiA6IG1heCBmYWlsdXJlc1xuICAgICAgbGFuLS0-aW50ZXJuZXQgOiBjaGVjayBzdWNjZWVkZWRcbiAgICB9XG4gICAgY29ubmVjdGVkLS0-ZGlzY29ubmVjdGVkIDogaWZkb3duXG4gICAgZGlzY29ubmVjdGVkLS0-bGFuIDogaWZ1cFxuICAgIFxuIiwibWVybWFpZCI6IntcbiAgXCJ0aGVtZVwiOiBcImRlZmF1bHRcIlxufSIsInVwZGF0ZUVkaXRvciI6ZmFsc2UsImF1dG9TeW5jIjp0cnVlLCJ1cGRhdGVEaWFncmFtIjpmYWxzZX0)
   """
 
   @min_interval 500
@@ -36,6 +42,12 @@ defmodule VintageNet.Connectivity.CheckLogic do
     %{connectivity: :disconnected, strikes: @max_fails_in_a_row, interval: :infinity}
   end
 
+  @doc """
+  Call this when the interface comes up
+
+  It is assumed that the interface has LAN connectivity now and a check will
+  be scheduled to happen shortly.
+  """
   @spec ifup(state()) :: state()
   def ifup(%{connectivity: :disconnected} = state) do
     # Physical layer is up. Optimistically assume that the LAN is accessible and
@@ -45,12 +57,21 @@ defmodule VintageNet.Connectivity.CheckLogic do
 
   def ifup(state), do: state
 
+  @doc """
+  Call this when the interface goes down
+
+  The interface will be categorized as `:disconnected` until `ifup/1` gets
+  called again.
+  """
   @spec ifdown(state()) :: state()
   def ifdown(state) do
     # Physical layer is down. Don't poll for connectivity since it won't happen.
     %{state | connectivity: :disconnected, interval: :infinity}
   end
 
+  @doc """
+  Call this when an Internet connectivity check succeeds
+  """
   @spec check_succeeded(state()) :: state()
   def check_succeeded(%{connectivity: :disconnected} = state), do: state
 
@@ -60,6 +81,12 @@ defmodule VintageNet.Connectivity.CheckLogic do
     %{state | connectivity: :internet, strikes: 0, interval: @max_interval}
   end
 
+  @doc """
+  Call this when an Internet connectivity check fails
+
+  Depending on how many failures have happened it a row, the connectivity may
+  be degraded to `:lan`.
+  """
   @spec check_failed(state()) :: state()
   def check_failed(%{connectivity: :internet} = state) do
     # There's no discernment between types of failures. Everything means

lib/vintage_net/connectivity/internet_checker.ex

@@ -48,7 +48,7 @@ defmodule VintageNet.Connectivity.InternetChecker do
   def handle_continue(:continue, %{ifname: ifname} = state) do
     VintageNet.subscribe(lower_up_property(ifname))
 
-    # Always run ifup and ifdown depeneding on the interface even
+    # Always run ifup and ifdown depending on the interface even
     # if it's redundant. There may have been a crash and this will
     # get our connectivity status back in sync.
     new_state =