add basic documentation to the primitives

Author: boydm

lib/scenic/component.ex

@@ -4,7 +4,41 @@
 #
 
 defmodule Scenic.Component do
-  @moduledoc false
+  @moduledoc """
+  A Component is simply a Scene that is optimized to be referenced by another scene.
+
+  All you need to do to create a Component is call
+
+      use Scenic.Component
+
+  instead of 
+
+      use Scenic.Scene
+
+  At the top of your module definition.
+
+  ## Verifiers
+
+  One of the main differences between a Component and a Scene is the two extra callbacks
+  that are used to verify incoming data. Since Components are meant to be reused, you
+  should do some basic validation that the data being set up is valid, then provide
+  feedback if it isn't.
+
+  ## No children
+
+  There is an optimization you can use. If you know for certain that your component
+  will not attempt to use any components, you can set `has_children` to `false` like this.
+
+      use Scenic.Component, has_children: false
+
+  Setting `has_children` to `false` this will do two things. First, it won't create
+  a dynamic supervisor for this scene, which saves some resources. Second,
+  `push_graph/1` goes through a fast pass that doesn't scan the graph for dynamic children.
+
+  For example, the Button component sets `has_children` to `false`.
+
+  This option is available for any Scene, not just components
+  """
 
   alias Scenic.Primitive
 

lib/scenic/primitive.ex

@@ -93,15 +93,15 @@ defmodule Scenic.Primitive do
     quote do
       @behaviour Scenic.Primitive
 
+      @doc false
       def build(data \\ nil, opts \\ [])
-
       def build(data, opts) do
         data = verify!(data)
         Primitive.build(__MODULE__, data, opts)
       end
 
+      @doc false
       def add_to_graph(graph, data \\ nil, opts \\ [])
-
       def add_to_graph(%Scenic.Graph{} = graph, data, opts) do
         Graph.add(graph, __MODULE__, data, opts)
       end
@@ -142,8 +142,11 @@ defmodule Scenic.Primitive do
       def default_pin(_), do: {0.0, 0.0}
 
       # simple defaults that can be overridden
+      @doc false
       def get(%Primitive{data: data}), do: data
+      @doc false
       def put(p, data), do: Primitive.do_put(p, data)
+
       @doc false
       def normalize(data), do: data
 

lib/scenic/primitive/arc.ex

@@ -4,7 +4,34 @@
 #
 
 defmodule Scenic.Primitive.Arc do
-  @moduledoc false
+  @moduledoc """
+  Draw an arc on the screen.
+
+  An arc is a segment that traces part of the outline of a circle. If you are
+  looking for something shaped like a piece of pie, then you want a segment.
+
+  Arcs are often drawn on top of a segment to get an affect where a piece of pie
+  is filled in, but only the curvy edge is stroked.
+
+  Note that you can fill an arc, but that will result in a shape that looks
+  like a potato wedge.
+
+  ## Data
+
+  `{radius, start, finish}`
+
+  The data for an arc is a three-tuple.
+  * `radius` - the radius of the arc
+  * `start` - the starting angle in radians
+  * `finish` - end ending angle in radians
+
+  ## Styles
+
+  This primitive recognizes the following styles
+  * `hidden` - show or hide the primitive
+  * `fill` - fill in the area of the primitive
+  * `stroke` - stroke the outline of the primitive. In this case, only the curvy part.
+  """
 
   use Scenic.Primitive
   alias Scenic.Primitive.Sector
@@ -16,6 +43,7 @@ defmodule Scenic.Primitive.Arc do
   # data verification and serialization
 
   # --------------------------------------------------------
+  @doc false
   def info(data),
     do: """
       #{IO.ANSI.red()}#{__MODULE__} data must be: {radius, start, finish}
@@ -24,6 +52,7 @@ defmodule Scenic.Primitive.Arc do
     """
 
   # --------------------------------------------------------
+  @doc false
   def verify(data) do
     normalize(data)
     {:ok, data}
@@ -32,12 +61,16 @@ defmodule Scenic.Primitive.Arc do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec normalize({number(), number(), number()}) :: {number(), number(), number()}
   def normalize({radius, start, finish} = data)
       when is_number(start) and is_number(finish) and is_number(radius),
       do: data
 
   # ============================================================================
+  @doc """
+  Returns a list of styles recognized by this primitive.
+  """
   @spec valid_styles() :: [:fill | :hidden | :stroke]
   def valid_styles(), do: @styles
 

lib/scenic/primitive/circle.ex

@@ -4,7 +4,23 @@
 #
 
 defmodule Scenic.Primitive.Circle do
-  @moduledoc false
+  @moduledoc """
+  Draw a circle on the screen.
+
+  ## Data
+
+  `radius`
+
+  The data for an arc is a single number.
+  * `radius` - the radius of the arc
+
+  ## Styles
+
+  This primitive recognizes the following styles
+  * `hidden` - show or hide the primitive
+  * `fill` - fill in the area of the primitive
+  * `stroke` - stroke the outline of the primitive.
+  """
 
   use Scenic.Primitive
 
@@ -14,6 +30,7 @@ defmodule Scenic.Primitive.Circle do
   # data verification and serialization
 
   # --------------------------------------------------------
+  @doc false
   def info(data),
     do: """
       #{IO.ANSI.red()}#{__MODULE__} data must be: radius
@@ -22,6 +39,7 @@ defmodule Scenic.Primitive.Circle do
     """
 
   # --------------------------------------------------------
+  @doc false
   def verify(data) do
     normalize(data)
     {:ok, data}
@@ -30,12 +48,16 @@ defmodule Scenic.Primitive.Circle do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec normalize(number()) :: number()
   def normalize(radius) when is_number(radius) do
     radius
   end
 
   # ============================================================================
+  @doc """
+  Returns a list of styles recognized by this primitive.
+  """
   @spec valid_styles() :: [:hidden | :fill | :stroke]
   def valid_styles(), do: @styles
 

lib/scenic/primitive/ellipse.ex

@@ -4,7 +4,27 @@
 #
 
 defmodule Scenic.Primitive.Ellipse do
-  @moduledoc false
+  @moduledoc """
+  Draw an ellipse on the screen.
+
+  ## Data
+
+  `{radius_1, radius_2}`
+
+  The data for an arc is a single number.
+  * `radius_1` - the radius of the ellipse in one direction
+  * `radius_2` - the radius of the ellipse in the other direction
+
+  ## Styles
+
+  This primitive recognizes the following styles
+  * `hidden` - show or hide the primitive
+  * `fill` - fill in the area of the primitive
+  * `stroke` - stroke the outline of the primitive.
+
+  Note: you can achieve the same effect with a Circle primitive
+  by applying a :size transform to it with unequal values on the axes
+  """
 
   use Scenic.Primitive
 
@@ -14,6 +34,7 @@ defmodule Scenic.Primitive.Ellipse do
   # data verification and serialization
 
   # --------------------------------------------------------
+  @doc false
   def info(data),
     do: """
       #{IO.ANSI.red()}#{__MODULE__} data must be: {radius_1, radius_2}
@@ -22,6 +43,7 @@ defmodule Scenic.Primitive.Ellipse do
     """
 
   # --------------------------------------------------------
+  @doc false
   def verify(data) do
     normalize(data)
     {:ok, data}
@@ -30,12 +52,16 @@ defmodule Scenic.Primitive.Ellipse do
   end
 
   # --------------------------------------------------------
+  @doc false
   @spec normalize({number(), number()}) :: {number(), number()}
   def normalize({r1, r2} = data) when is_number(r1) and is_number(r2) do
     data
   end
 
   # ============================================================================
+  @doc """
+  Returns a list of styles recognized by this primitive.
+  """
   @spec valid_styles() :: [:fill | :hidden | :stroke, ...]
   def valid_styles(), do: @styles
 

lib/scenic/primitive/group.ex

@@ -4,7 +4,25 @@
 #
 
 defmodule Scenic.Primitive.Group do
-  @moduledoc false
+  @moduledoc """
+  A container to hold other primitives.
+
+  Any styles placed on a group will be inherited by the primitives in the 
+  group. Any transforms placed on a group will be multiplied into the transforms
+  in the primitives in the group.
+
+  ## Data
+
+  `uids`
+
+  The data for an arc is a list of internal uids for the primitives it contains
+
+
+  ## Styles
+
+  The group is special in that it accepts all styles and transforms, even if they
+  are non-standard. These are then inherited by any primitives, including SceneRefs
+  """
 
   use Scenic.Primitive
   alias Scenic.Primitive
@@ -15,14 +33,15 @@ defmodule Scenic.Primitive.Group do
   # data verification and serialization
 
   # --------------------------------------------------------
+  @doc false
   def build(nil, opts), do: build([], opts)
-
   def build(ids, opts) do
     verify!(ids)
     Primitive.build(__MODULE__, ids, opts)
   end
 
   # --------------------------------------------------------
+  @doc false
   def info(data),
     do: """
       #{IO.ANSI.red()}#{__MODULE__} data must be a list of valid uids of other elements in the graph.
@@ -31,6 +50,7 @@ defmodule Scenic.Primitive.Group do
     """
 
   # --------------------------------------------------------
+  @doc false
   def verify(ids) when is_list(ids) do
     if Enum.all?(ids, &is_integer/1), do: {:ok, ids}, else: :invalid_data
   end
@@ -40,6 +60,9 @@ defmodule Scenic.Primitive.Group do
   # ============================================================================
   # filter and gather styles
 
+  @doc """
+  Returns a list of styles recognized by this primitive.
+  """
   @spec valid_styles() :: [:all, ...]
   def valid_styles(), do: [:all]
 

lib/scenic/primitive/line.ex

@@ -4,7 +4,24 @@
 #
 
 defmodule Scenic.Primitive.Line do
-  @moduledoc false
+  @moduledoc """
+  Draw a line on the screen.
+
+  ## Data
+
+  `{point_a, point_b}`
+
+  The data for a line is a tuple containing two points.
+  * `point_a` - position to start drawing from
+  * `point_b` - position to draw to
+
+  ## Styles
+
+  This primitive recognizes the following styles
+  * `hidden` - show or hide the primitive
+  * `cap` - says how to draw the ends of the line.
+  * `stroke` - stroke the outline of the primitive.
+  """
 
   use Scenic.Primitive
 
@@ -16,6 +33,7 @@ defmodule Scenic.Primitive.Line do
   # data verification and serialization
 
   # --------------------------------------------------------
+  @doc false
   def info(data),
     do: """
       #{IO.ANSI.red()}#{__MODULE__} data must be two points: {{x0,y0}, {x1,y1}}
@@ -24,13 +42,17 @@ defmodule Scenic.Primitive.Line do
     """
 
   # --------------------------------------------------------
+  @doc false
   def verify({{x0, y0}, {x1, y1}} = data)
       when is_number(x0) and is_number(y0) and is_number(x1) and is_number(y1),
       do: {:ok, data}
 
   def verify(_), do: :invalid_data
 
   # ============================================================================
+  @doc """
+  Returns a list of styles recognized by this primitive.
+  """
   @spec valid_styles() :: [:cap | :hidden | :stroke, ...]
   def valid_styles(), do: @styles