add docs for input and event callbacks

Author: boydm

lib/scenic/scene.ex

@@ -342,9 +342,87 @@ defmodule Scenic.Scene do
   # ============================================================================
   # callback definitions
 
+  @doc """
+  Invoked when the `Scene` receives input from a driver.
+
+  Input is messages sent directly from a driver, usually based on some action by the user.
+  This is opposed to "events", which are generated by other scenes.
+
+  When input arrives at a scene, you can consume it, or pass it along to the scene above
+  you in the ViewPort's supervision structure.
+
+  To consume the input and have processing stop afterward, return either a `{:halt, ...}` or
+  `{:noreply, ...}` value. They are effectively the same thing.
+
+  To allow the scene's parent to process the input, return `{:cont, input, state, ...}`. Note
+  that you can pass along the input unchanged or transform it in the process if you wish.
+
+  The callback supports all the return values of the
+  [`init`](https://hexdocs.pm/elixir/GenServer.html#c:handle_cast/2)
+  callback in [`Genserver`](https://hexdocs.pm/elixir/GenServer.html).
+
+  In addition to the normal return values defined by GenServer, a `Scene` can
+  add an optional `{push: graph}` term, which pushes the graph to the viewport.
+
+  This has replaced push_graph() as the preferred way to push a graph.
+  """
   @callback handle_input(input :: any, context :: Context.t(), state :: any) ::
-              {:noreply, state :: any}
-  @callback filter_event(any, any, any) :: {:cont, any, any} | {:halt, any}
+              {:noreply, new_state}
+              | {:noreply, new_state}
+              | {:noreply, new_state, timeout}
+              | {:noreply, new_state, :hibernate}
+              | {:noreply, new_state, opts :: response_opts()}
+              | {:halt, new_state}
+              | {:halt, new_state, timeout}
+              | {:halt, new_state, :hibernate}
+              | {:halt, new_state, opts :: response_opts()}
+              | {:cont, input, new_state}
+              | {:cont, input, new_state, timeout}
+              | {:cont, input, new_state, :hibernate}
+              | {:cont, input, new_state, opts :: response_opts()}
+              | {:stop, reason, new_state}
+            when new_state: term, reason: term, input: term
+
+  @doc """
+  Invoked when the `Scene` receives an event from another scene.
+
+  Events are messages generated by a scene, that are passed backwards up the ViewPort's
+  scene supervision tree. This is opposed to "input", which comes directly from the drivers.
+
+  When an event arrives at a scene, you can consume it, or pass it along to the scene above
+  you in the ViewPort's supervision structure.
+
+  To consume the input and have processing stop afterward, return either a `{:halt, ...}` or
+  `{:noreply, ...}` value. They are effectively the same thing.
+
+  To allow the scene's parent to process the input, return `{:cont, event, state, ...}`. Note
+  that you can pass along the event unchanged or transform it in the process if you wish.
+
+  The callback supports all the return values of the
+  [`init`](https://hexdocs.pm/elixir/GenServer.html#c:handle_cast/2)
+  callback in [`Genserver`](https://hexdocs.pm/elixir/GenServer.html).
+
+  In addition to the normal return values defined by GenServer, a `Scene` can
+  add an optional `{push: graph}` term, which pushes the graph to the viewport.
+
+  This has replaced push_graph() as the preferred way to push a graph.
+  """
+  @callback filter_event(event :: term, from :: pid, state :: term) ::
+              {:noreply, new_state}
+              | {:noreply, new_state}
+              | {:noreply, new_state, timeout}
+              | {:noreply, new_state, :hibernate}
+              | {:noreply, new_state, opts :: response_opts()}
+              | {:halt, new_state}
+              | {:halt, new_state, timeout}
+              | {:halt, new_state, :hibernate}
+              | {:halt, new_state, opts :: response_opts()}
+              | {:cont, event, new_state}
+              | {:cont, event, new_state, timeout}
+              | {:cont, event, new_state, :hibernate}
+              | {:cont, event, new_state, opts :: response_opts()}
+              | {:stop, reason, new_state}
+            when new_state: term, reason: term, event: term
 
   @doc """
   Invoked when the `Scene` is started.