docs cleanup. Add caret and ratio_button

Author: boydm

lib/scenic/component/button.ex

@@ -91,6 +91,7 @@ defmodule Scenic.Component.Button do
   @default_alignment :center
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Button data must be a bitstring: initial_text
@@ -100,10 +101,12 @@ defmodule Scenic.Component.Button do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify(text) when is_bitstring(text), do: {:ok, text}
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init(text, opts) when is_bitstring(text) and is_list(opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -185,6 +188,7 @@ defmodule Scenic.Component.Button do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input(
         {:cursor_enter, _uid},
         _context,

lib/scenic/component/input/caret.ex

@@ -4,8 +4,28 @@
 #
 
 defmodule Scenic.Component.Input.Caret do
-  @moduledoc false
+  @moduledoc """
+  Add a blinking text-input caret to a graph.
 
+
+  ## Data
+
+  `{height, color}`
+
+  * `height` - integer greater than zero
+  * `color` - any [valid color](Scenic.Primitive.Style.Paint.Color.html).
+
+  ## Usage
+
+  The caret component is used by the TextField component and usually isn't accessed directly,
+  although you are free to do so if it fits your needs. There is no short-cut helper
+  function so you will need to add it to the graph manually.
+
+  The following example adds a caret to a graph.
+
+      graph
+      |> Caret.add_to_graph({height, theme.text}, id: :caret)
+  """
   use Scenic.Component, has_children: false
 
   import Scenic.Primitives,
@@ -28,6 +48,7 @@ defmodule Scenic.Component.Input.Caret do
   # setup
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Caret data must be: {height, color}
@@ -37,6 +58,7 @@ defmodule Scenic.Component.Input.Caret do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec verify(any()) :: :invalid_data | {:ok, {number(), any()}}
   def verify({height, color} = data)
       when is_number(height) and height > 0 do
@@ -49,6 +71,7 @@ defmodule Scenic.Component.Input.Caret do
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init({height, color}, _opts) do
     # build the graph, initially not showing
     graph =
@@ -72,6 +95,7 @@ defmodule Scenic.Component.Input.Caret do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_cast(:start_caret, %{graph: graph, timer: nil} = state) do
     # turn on the caret
     graph =
@@ -127,6 +151,7 @@ defmodule Scenic.Component.Input.Caret do
   def handle_cast(_, state), do: {:noreply, state}
 
   # --------------------------------------------------------
+  @doc false
   def handle_info(:blink, %{graph: graph, hidden: hidden} = state) do
     # invert the hidden flag
     hidden = !hidden

lib/scenic/component/input/checkbox.ex

@@ -66,7 +66,8 @@ defmodule Scenic.Component.Input.Checkbox do
   # @default_height    16
   # @default_radius    3
 
-  #  #--------------------------------------------------------
+  # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Checkbox data must be: {text, checked?}
@@ -76,13 +77,15 @@ defmodule Scenic.Component.Input.Checkbox do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify({text, checked} = data) when is_bitstring(text) and is_boolean(checked) do
     {:ok, data}
   end
 
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init({text, checked?}, opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -149,6 +152,7 @@ defmodule Scenic.Component.Input.Checkbox do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_enter, _uid}, _, %{pressed: true} = state) do
     state = Map.put(state, :contained, true)
     graph = update_graph(state)

lib/scenic/component/input/dropdown.ex

@@ -109,6 +109,7 @@ defmodule Scenic.Component.Input.Dropdown do
   @rotate_up :math.pi()
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Dropdown data must be: {items, initial}
@@ -118,6 +119,7 @@ defmodule Scenic.Component.Input.Dropdown do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify({items, initial} = data) when is_list(items) do
     (Enum.all?(items, &verify_item(&1)) &&
        Enum.find_value(items, false, fn {_, id} -> id == initial end))
@@ -134,6 +136,7 @@ defmodule Scenic.Component.Input.Dropdown do
   defp verify_item(_), do: false
 
   # --------------------------------------------------------
+  @doc false
   # credo:disable-for-next-line Credo.Check.Refactor.CyclomaticComplexity
   def init({items, initial_id}, opts) do
     id = opts[:id]
@@ -263,6 +266,7 @@ defmodule Scenic.Component.Input.Dropdown do
   # tracking when the dropdown is UP
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_enter, _uid}, %{id: id}, %{down: false} = state) do
     {:noreply, %{state | hover_id: id}}
   end

lib/scenic/component/input/radio_button.ex

@@ -1,5 +1,29 @@
 defmodule Scenic.Component.Input.RadioButton do
-  @moduledoc false
+  @moduledoc """
+  Add a single radio button to a graph.
+
+  ## Data
+
+  `{text, id}`
+  `{text, id, selected?}`
+
+  * `text` - a bitstring of the text to display
+  * `id` - any term. Identifies the radio button.
+  * `selected?` - boolean. `true` if selected. `false if not`. Default is `false` if
+  this term is not provided.
+
+  ## Usage
+
+  The RadioButton component is used by the RadioGroup component and usually isn't accessed
+  directly, although you are free to do so if it fits your needs. There is no short-cut
+  helper function so you will need to add it to the graph manually.
+
+  The following example adds a caret to a graph.
+
+      graph
+      |> RadioButton.add_to_graph({"A button", :an_id, true})
+
+  """
 
   use Scenic.Component, has_children: false
 
@@ -11,7 +35,8 @@ defmodule Scenic.Component.Input.RadioButton do
 
   # import IEx
 
-  #  #--------------------------------------------------------
+  #--------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}RadioButton data must be: {text, id} or {text, id, checked?}
@@ -21,6 +46,7 @@ defmodule Scenic.Component.Input.RadioButton do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify({text, _} = data) when is_bitstring(text) do
     {:ok, data}
   end
@@ -32,6 +58,7 @@ defmodule Scenic.Component.Input.RadioButton do
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init({text, id}, opts) when is_bitstring(text), do: init({text, id, false}, opts)
 
   def init({text, id, checked?}, opts) do
@@ -69,14 +96,8 @@ defmodule Scenic.Component.Input.RadioButton do
     {:ok, state}
   end
 
-  # # --------------------------------------------------------
-  # def handle_cast({:set_value, new_value}, state) do
-  #   state = Map.put(state, :checked, new_value)
-  #   graph = update_graph(state)
-  #   {:noreply, %{state | graph: graph}}
-  # end
-
   # --------------------------------------------------------
+  @doc false
   def handle_cast({:set_to_msg, set_id}, %{id: id} = state) do
     state = Map.put(state, :checked, set_id == id)
     graph = update_graph(state)
@@ -98,6 +119,7 @@ defmodule Scenic.Component.Input.RadioButton do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_button, {:left, :press, _, _}}, context, state) do
     state =
       state

lib/scenic/component/input/radio_group.ex

@@ -84,7 +84,8 @@ defmodule Scenic.Component.Input.RadioGroup do
 
   @line_height 22
 
-  #  #--------------------------------------------------------
+  #--------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}RadioGroup data must be a list of items
@@ -103,6 +104,7 @@ defmodule Scenic.Component.Input.RadioGroup do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify(items) when is_list(items) do
     items
     |> Enum.all?(fn item ->
@@ -120,9 +122,7 @@ defmodule Scenic.Component.Input.RadioGroup do
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
-  # def valid?( _items ), do: true
-
-  # --------------------------------------------------------
+  @doc false
   def init(items, opts) when is_list(items) do
     id = opts[:id]
     styles = opts[:styles]
@@ -171,6 +171,7 @@ defmodule Scenic.Component.Input.RadioGroup do
 
   # ============================================================================
 
+  @doc false
   def filter_event({:click, btn_id}, _from, %{id: id} = state) do
     Scene.cast_to_refs(nil, {:set_to_msg, btn_id})
 

lib/scenic/component/input/slider.ex

@@ -87,6 +87,7 @@ defmodule Scenic.Component.Input.Slider do
   # setup
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Slider data must be: {extents, initial_value}
@@ -103,6 +104,7 @@ defmodule Scenic.Component.Input.Slider do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify({ext, initial} = data) do
     verify_initial(ext, initial)
     |> case do
@@ -127,6 +129,7 @@ defmodule Scenic.Component.Input.Slider do
   defp verify_initial(_, _), do: false
 
   # --------------------------------------------------------
+  @doc false
   def init({extents, value}, opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -163,6 +166,7 @@ defmodule Scenic.Component.Input.Slider do
   # ============================================================================
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_button, {:left, :press, _, {x, _}}}, context, state) do
     state =
       state

lib/scenic/component/input/text_field.ex

@@ -112,6 +112,7 @@ defmodule Scenic.Component.Input.TextField do
   @hint_color :grey
 
   # --------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}TextField data must be a bitstring: initial_text
@@ -121,13 +122,15 @@ defmodule Scenic.Component.Input.TextField do
   end
 
   # --------------------------------------------------------
+  @doc false
   def verify(initial_text) when is_bitstring(initial_text) do
     {:ok, initial_text}
   end
 
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   def init(value, opts) do
     id = opts[:id]
     styles = opts[:styles]
@@ -333,6 +336,7 @@ defmodule Scenic.Component.Input.TextField do
   # User input handling - get the focus
 
   # --------------------------------------------------------
+  @doc false
   # unfocused click in the text field
   def handle_input(
         {:cursor_button, {:left, :press, _, _}},

lib/scenic/component/input/toggle.ex

@@ -95,7 +95,8 @@ defmodule Scenic.Component.Input.Toggle do
           }
   end
 
-  #  #--------------------------------------------------------
+  #--------------------------------------------------------
+  @doc false
   def info(data) do
     """
     #{IO.ANSI.red()}Toggle data must be: on?
@@ -105,6 +106,7 @@ defmodule Scenic.Component.Input.Toggle do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec verify(any) :: {:ok, boolean} | :invalid_data
   def verify(on? = data) when is_boolean(on?) do
     {:ok, data}
@@ -113,6 +115,7 @@ defmodule Scenic.Component.Input.Toggle do
   def verify(_), do: :invalid_data
 
   # --------------------------------------------------------
+  @doc false
   @spec init(any, Keyword.t() | map | nil) :: {:ok, State.t()}
   def init(on?, opts) do
     id = opts[:id]
@@ -195,6 +198,7 @@ defmodule Scenic.Component.Input.Toggle do
   end
 
   # --------------------------------------------------------
+  @doc false
   def handle_input({:cursor_enter, _uid}, _, %{pressed?: true} = state) do
     state = Map.put(state, :contained?, true)
     graph = update_graph(state)