 defmodule Baumeister.Observer do
+  @moduledoc """
+  Defines the API, which a specific observer has to implement.
+  """
   alias Baumeister.EventCenter
   alias Baumeister.BaumeisterFile
   alias Baumeister.Observer
-  @moduledoc """
-  Defines the API, which a specific observer has to implement.
+
+  @typedoc """
+  A mapping between plugin name and its current state.
   """
+  @type plugin_state :: %{atom => any}
+
+  @typedoc """
+  Allowed return values for an Observer Plugin:
+  * `:ok` if everything went fine. We return the URL and BaumeisterFile.
+  * `:error` somethings fails. Stops the Observer with a crash
+  * `:stop` The Plugin decides, that the Observer should stop.
+  """
+  @type observer_return_t ::
+    {:ok, String.t, String.t, any} |
+    {:ok, any} |
+    {:error, any, any} |
+    {:stop, any}
+
 
   @doc """
   Initializes the observer. It is called with the observer's

  ###################################################

  use GenServer

  defstruct [:mod, :state, :observer_pid]

  def start_link(mod, configuration) when is_atom(mod) do
    GenServer.start_link(__MODULE__, [mod, configuration])
  end

  @doc """

  the URL of the target repository and the content of the `BaumeisterFile`,
  which is used to determine the nodes to execute the build.
  """
  @callback observe(state :: any) :: observer_return_t

  ###################################################
  ##
