Add docs for Scenic.Primitive and rename Primitive.put_opts to Primitive.merge_opts

Author: boydm

CHANGELOG.md

@@ -5,6 +5,8 @@
 * Simplify rules around user-closing a viewport
 * Fix bug where captured positional inputs were not casting the transformed location
 * Deprecate Graph.get_root(). Use Graph.get!(graph, :\_root\_) instead.
+* Renamed Primitive.put_opts to Primitive.merge_opts
+
 
 ## 0.8.0
 

lib/scenic/primitive.ex

@@ -4,7 +4,29 @@
 #
 
 defmodule Scenic.Primitive do
-  @moduledoc false
+  @moduledoc """
+  Please see [`Primitives Overview`](overview_primitives.html) for a high-level description.
+
+  ## What is a primitive
+
+  A primitive is the simplest thing Scenic knows how to draw on the screen. There is is only
+  a small, fixed set of them, but they can be combined in a graph to draw very complicated
+  images.
+
+  In general, each Primitive type has a piece of data that it expects to operate on. For
+  example, Primitive.Text requires a bitstring. Primitive.Circle requires a radius. Please
+  see the documentation for each primitive for details.
+
+  ## How to use primitives
+
+  By far, the easiest way to use primitives is to import the helper functions in
+  [`Scenic.Primitives`](Scenic.Primitives.html). These helpers can both add primitives to
+  a scene you are building and modify later as you react to events.
+
+  Once you get a primitive out of a graph via functions such as `Graph.modify`, or `Graph.get`,
+  You can use the generic helpers in this module to access or manipulate them. 
+  """
+
 
   alias Scenic.Graph
   alias Scenic.Primitive
@@ -149,6 +171,21 @@ defmodule Scenic.Primitive do
   # build a new primitive
   # in general, default the various lists and the assign map to nil to save space
   # assume most elements do not hvae these items set.
+
+  @doc """
+  Generic builder to create a new primitive.
+
+  This function is used internally. You should almost always use the helpers in
+  [Scenic.Primitives](Scenic.Primitives.html) instead.
+
+  Parameters:
+  `module` - The module of the primitive you are building
+  `data` - the primitive-specific data being set into the primitive
+  `opts` - a list of style and transform options to apply to the primitive
+
+  Returns the built primitive.
+  """
+
   @spec build(module :: atom, data :: any, opts :: keyword) :: Primitive.t()
   def build(module, data, opts \\ []) do
     # first build the map with the non-optional fields
@@ -256,22 +293,32 @@ defmodule Scenic.Primitive do
 
   # ============================================================================
   # styles
-  # I'm allowing the styles to not be present on the primitive, which is why
-  # I'm not parsing it out in the function match
 
+  @doc """
+  Get the styles map from a primitive.
+
+  Parameters:
+  `primitive` - The primitive
+
+  Returns the a map of styles set directly onto this primitive. This does 
+  not include any inherited styles.
+  """
   @spec get_styles(primitive :: Primitive.t()) :: map
   def get_styles(primitive)
 
   def get_styles(%Primitive{} = p) do
     Map.get(p, :styles, %{})
   end
 
-  # def get_primitive_styles( primitive )
-  # def get_primitive_styles( %Primitive{} = p ) do
-  #   Map.get(p, :styles, %{})
-  #   |> Style.primitives()
-  # end
+  @doc """
+  Update the styles map in a primitive.
+
+  Parameters:
+  `primitive` - The primitive
+  `styles` - The new styles map
 
+  Returns the primitive with the updated styles.
+  """
   @spec put_styles(primitive :: Primitive.t(), styles :: map) :: Primitive.t()
   def put_styles(primitve, styles)
   def put_styles(%Primitive{} = p, nil), do: Map.delete(p, :styles)
@@ -284,13 +331,33 @@ defmodule Scenic.Primitive do
   @spec get_style(primitive :: Primitive.t(), type :: atom, default :: any) :: any
   def get_style(primitive, type, default \\ nil)
 
+  @doc """
+  Get the value of a specific style set on the primitive.
+
+  If the style is not set, it returns default
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the style to get.
+  `default` - default value to return if the style is not set.
+
+  Returns the value of the style.
+  """
   def get_style(%Primitive{} = p, type, default) when is_atom(type) do
     Map.get(p, :styles, %{})
     |> Map.get(type, default)
   end
 
-  # the public facing put_style gives the primitive module a chance to filter the styles
-  # do_put_style does the actual work
+  @doc """
+  Update the value of a specific style set on the primitive.
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the style to get.
+  `data` - the value to set on the style.
+
+  Returns the updated primitive.
+  """
   @spec put_style(primitive :: Primitive.t(), type :: atom, data :: any) :: Primitive.t()
   def put_style(%Primitive{} = p, type, nil) when is_atom(type) do
     Map.get(p, :styles, %{})
@@ -310,6 +377,17 @@ defmodule Scenic.Primitive do
     end)
   end
 
+  @doc """
+  Deletes a specified style from a primitive.
+
+  Does nothing if the style is not set.
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the style to delete.
+
+  Returns the updated primitive.
+  """
   @spec delete_style(primitive :: Primitive.t(), type :: atom) :: Primitive.t()
   def delete_style(primitive, type)
 
@@ -321,16 +399,32 @@ defmodule Scenic.Primitive do
 
   # ============================================================================
   # transforms
-  # I'm allowing the transforms to not be present on the primitive, which is why
-  # I'm not parsing it out in the function match
 
+  @doc """
+  Get the transforms map from a primitive.
+
+  Parameters:
+  `primitive` - The primitive
+
+  Returns the a map of transforms set directly onto this primitive. This does 
+  not include any inherited transforms.
+  """
   @spec get_transforms(primitive :: Primitive.t()) :: map
   def get_transforms(primitive)
 
   def get_transforms(%Primitive{} = p) do
     Map.get(p, :transforms, %{})
   end
 
+  @doc """
+  Update the transforms map in a primitive.
+
+  Parameters:
+  `primitive` - The primitive
+  `transforms` - The new transforms map
+
+  Returns the primitive with the updated transforms.
+  """
   @spec put_transforms(primitive :: Primitive.t(), transforms :: map) :: Primitive.t()
   def put_transforms(primitve, transforms)
   def put_transforms(%Primitive{} = p, nil), do: Map.delete(p, :transforms)
@@ -340,16 +434,37 @@ defmodule Scenic.Primitive do
     Map.put(p, :transforms, txs)
   end
 
+
   @spec get_transform(primitive :: Primitive.t(), type :: atom, default :: any) :: any
   def get_transform(primitive, tx_type, default \\ nil)
 
+  @doc """
+  Get the value of a specific transform set on the primitive.
+
+  If the transform is not set, it returns default
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the transform to get.
+  `default` - default value to return if the transform is not set.
+
+  Returns the value of the transform.
+  """
   def get_transform(%Primitive{} = p, tx_type, default) when is_atom(tx_type) do
     Map.get(p, :transforms, %{})
     |> Map.get(tx_type, default)
   end
 
-  # the public facing put_style gives the primitive module a chance to filter the styles
-  # do_put_style does the actual work
+  @doc """
+  Update the value of a specific transform set on the primitive.
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the transform to get.
+  `data` - the value to set on the transform.
+
+  Returns the updated primitive.
+  """
   @spec put_transform(primitive :: Primitive.t(), type :: atom, transform :: any) :: Primitive.t()
   def put_transform(%Primitive{} = p, tx_type, nil) when is_atom(tx_type) do
     Map.get(p, :transforms, %{})
@@ -369,6 +484,18 @@ defmodule Scenic.Primitive do
     end)
   end
 
+
+  @doc """
+  Deletes a specified transform from a primitive.
+
+  Does nothing if the transform is not set.
+
+  Parameters:
+  `primitive` - The primitive
+  `type` - atom representing the transform to delete.
+
+  Returns the updated primitive.
+  """
   @spec delete_transform(primitive :: Primitive.t(), type :: atom) :: Primitive.t()
   def delete_transform(primitive, tx_type)
 
@@ -380,6 +507,15 @@ defmodule Scenic.Primitive do
 
   # ============================================================================
   # primitive-specific data
+
+  @doc """
+  Get the value of the primitive-specific data.
+
+  Parameters:
+  `primitive` - The primitive
+
+  Returns the value of the primitive-specific data.
+  """
   @spec get(primitive :: Primitive.t()) :: any
   def get(primitive)
 
@@ -388,13 +524,47 @@ defmodule Scenic.Primitive do
     mod.get(p)
   end
 
+  @deprecated "Use Primitive.merge_opts instead."
   @spec put_opts(primitive :: Primitive.t(), opts :: keyword) :: Primitive.t()
   def put_opts(primitive, opts)
 
   def put_opts(%Primitive{} = p, opts) when is_list(opts) do
+    raise "Primitive.put_opts has been deprecated. Use Primitive.merge_opts instead."
+  end
+
+
+  @doc """
+  Merge an options-list of styles and transforms onto a primitive.
+
+  This function might go through a name-change in the future. It is really
+  more of a merge. The supplied list of styles and transforms
+
+  Parameters:
+  `primitive` - The primitive
+
+  Returns the value of the primitive-specific data.
+  """
+  @spec merge_opts(primitive :: Primitive.t(), opts :: keyword) :: Primitive.t()
+  def merge_opts(primitive, opts)
+
+  def merge_opts(%Primitive{} = p, opts) when is_list(opts) do
     apply_options(p, opts)
   end
 
+  @doc """
+  Put primitive-specific data onto the primitive.
+
+  Like many of the functions in the Scenic.Primitive module, you are usually better
+  off using the helper functions in [`Scenic.Primitives`](Scenic.Primitives.html) instead.
+
+  Parameters:
+  `primitive` - The primitive
+  `data` - The data to set
+  `opts` - A list of style/transform options to merge
+
+  Returns the updated primitive.
+  """
+
   @spec put(primitive :: Primitive.t(), data :: any, opts :: list) :: Primitive.t()
   def put(primitive, data, opts \\ [])
 

lib/scenic/primitives.ex

@@ -862,7 +862,7 @@ defmodule Scenic.Primitives do
           options :: list
         ) :: Primitive.t()
 
-  def update_opts(p, opts), do: Primitive.put_opts(p, opts)
+  def update_opts(p, opts), do: Primitive.merge_opts(p, opts)
 
   # ============================================================================
   # generic workhorse versions

lib/scenic/view_port.ex

@@ -399,7 +399,7 @@ defmodule Scenic.ViewPort do
 
     # extract the viewport global styles. Do this by reusing tools in Primitive.
     p =
-      Primitive.put_opts(
+      Primitive.merge_opts(
         %Primitive{module: Primitive.Group},
         Map.get(config, :opts, [])
       )

test/scenic/primitive_test.exs

@@ -179,24 +179,24 @@ defmodule Scenic.PrimitiveTest do
   end
 
   # --------------------------------------------------------
-  # put
+  # merge_opts
 
-  test "put_opts updates only the options on a primitive" do
-    assert Primitive.put_opts(@primitive, fill: :blue).styles == %{
+  test "merge_opts updates only the options on a primitive" do
+    assert Primitive.merge_opts(@primitive, fill: :blue).styles == %{
              fill: :blue,
              stroke: {10, :green}
            }
   end
 
-  test "put_opts rejects invalid style" do
+  test "merge_opts rejects invalid style" do
     assert_raise Primitive.Style.FormatError, fn ->
-      Primitive.put_opts(@primitive, fill: :invalid)
+      Primitive.merge_opts(@primitive, fill: :invalid)
     end
   end
 
-  test "put_opts rejects invalid transform" do
+  test "merge_opts rejects invalid transform" do
     assert_raise Primitive.Transform.FormatError, fn ->
-      Primitive.put_opts(@primitive, rotate: :invalid)
+      Primitive.merge_opts(@primitive, rotate: :invalid)
     end
   end