Add docs about default callback implementation (#572)

* Add docs about default callback implementation * Update lib/membrane/element/base.ex Co-authored-by: Feliks Pobiedziński <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Feliks Pobiedziński <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Feliks Pobiedziński <[email protected]> * Upgrade docs * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/pipeline.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/element/base.ex Co-authored-by: Mateusz Front <[email protected]> * Extend docs for handle_init * Run mix format * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> * Standarization of added docs * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> * Update lib/membrane/bin.ex Co-authored-by: Mateusz Front <[email protected]> --------- Co-authored-by: Feliks Pobiedziński <[email protected]> Co-authored-by: [email protected] <[email protected]> Co-authored-by: Mateusz Front <[email protected]>
membraneframework · Jul 3, 2023 · b1cd21f · b1cd21f
1 parent cf0ae50
commit b1cd21f
Show file tree

Hide file tree

Showing 3 changed files with 41 additions and 4 deletions.
diff --git a/lib/membrane/bin.ex b/lib/membrane/bin.ex
@@ -42,6 +42,7 @@ defmodule Membrane.Bin do
   For these reasons, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
   while `handle_init` should be used for things like parsing options, initializing state or
   spawning children.
+  By default, it converts the opts struct to a map and sets them as the bin's state.
   """
   @callback handle_init(context :: CallbackContext.t(), options :: options) ::
               callback_return()
@@ -51,6 +52,7 @@ defmodule Membrane.Bin do
   ONLY for dynamic pads.
 
   Context passed to this callback contains additional field `:pad_options`.
+  By default, it does nothing.
   """
   @callback handle_pad_added(
               pad :: Pad.ref(),
@@ -63,6 +65,7 @@ defmodule Membrane.Bin do
   ONLY for dynamic pads.
 
   Context passed to this callback contains additional field `:pad_options`.
+  By default, it does nothing.
   """
   @callback handle_pad_removed(
               pad :: Pad.ref(),
@@ -74,6 +77,7 @@ defmodule Membrane.Bin do
   Callback invoked on bin startup, right after `c:handle_init/2`.
 
   Any long-lasting or complex initialization should happen here.
+  By default, it does nothing.
   """
   @callback handle_setup(
               context :: CallbackContext.t(),
@@ -82,6 +86,7 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when bin switches the playback to `:playing`.
+  By default, it does nothing.
   """
   @callback handle_playing(
               context :: CallbackContext.t(),
@@ -95,6 +100,7 @@ defmodule Membrane.Bin do
   The callback won't be invoked, when you have initiated the pad removal,
   eg. when you have returned `t:Membrane.Bin.Action.remove_link()` action
   which made one of your children's pads be removed.
+  By default, it does nothing.
   """
   @callback handle_child_pad_removed(
               child :: Child.name(),
@@ -105,6 +111,7 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when a notification comes in from an element.
+  By default, it ignores the received message.
   """
   @callback handle_child_notification(
               notification :: Membrane.ChildNotification.t(),
@@ -115,6 +122,7 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when a notification comes in from an parent.
+  By default, it ignores the received message.
   """
   @callback handle_parent_notification(
               notification :: Membrane.ParentNotification.t(),
@@ -127,6 +135,7 @@ defmodule Membrane.Bin do
   as an internal membrane message.
 
   Can be used for receiving data from non-membrane processes.
+  By default, it ignores the received message.
   """
   @callback handle_info(
               message :: any,
@@ -136,6 +145,7 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when a child element starts processing stream via given pad.
+  By default, it does nothing.
   """
   @callback handle_element_start_of_stream(
               child :: Child.name(),
@@ -146,6 +156,8 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when a child element finishes processing stream via given pad.
+
+  By default, it does nothing.
   """
   @callback handle_element_end_of_stream(
               child :: Child.name(),
@@ -156,6 +168,8 @@ defmodule Membrane.Bin do
 
   @doc """
   Callback invoked when children of `Membrane.ChildrenSpec` are started.
+
+  By default, it does nothing.
   """
   @callback handle_spec_started(
               children :: [Child.name()],
@@ -187,7 +201,7 @@ defmodule Membrane.Bin do
   @doc """
   A callback invoked when the bin is being removed by its parent.
 
-  By default it returns `t:Membrane.Bin.Action.terminate/0` with reason `:normal`.
+  By default, it returns `t:Membrane.Bin.Action.terminate/0` with reason `:normal`.
   """
   @callback handle_terminate_request(
               context :: CallbackContext.t(),

diff --git a/lib/membrane/element/base.ex b/lib/membrane/element/base.ex
@@ -45,6 +45,7 @@ defmodule Membrane.Element.Base do
   that happen in this callback crash the parent as well, regardless of crash groups.
   For these reasons, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
   while `handle_init` should be used for things like parsing options or initializing state.
+  By default, it converts the `opts` struct to a map and sets them as the element's state.
   """
   @callback handle_init(context :: CallbackContext.t(), options :: Element.options()) ::
               callback_return
@@ -53,6 +54,7 @@ defmodule Membrane.Element.Base do
   Callback invoked on element startup, right after `c:handle_init/2`.
 
   Any long-lasting or complex initialization should happen here.
+  By default, it does nothing.
   """
   @callback handle_setup(
               context :: CallbackContext.t(),
@@ -64,6 +66,7 @@ defmodule Membrane.Element.Base do
 
   From this point, element can send and receive buffers, events, stream formats and demands
   through its pads.
+  By default, it does nothing.
   """
   @callback handle_playing(
               context :: CallbackContext.t(),
@@ -75,6 +78,7 @@ defmodule Membrane.Element.Base do
   as an internal membrane message.
 
   Useful for receiving ticks from timer, data sent from NIFs or other stuff.
+  By default, it ignores the received message.
   """
   @callback handle_info(
               message :: any(),
@@ -87,6 +91,7 @@ defmodule Membrane.Element.Base do
   ONLY for dynamic pads.
 
   Context passed to this callback contains additional field `:pad_options`.
+  By default, it does nothing.
   """
   @callback handle_pad_added(
               pad :: Pad.ref(),
@@ -99,6 +104,7 @@ defmodule Membrane.Element.Base do
   ONLY for dynamic pads.
 
   Context passed to this callback contains additional field `:pad_options`.
+  By default, it does nothing.
   """
   @callback handle_pad_removed(
               pad :: Pad.ref(),
@@ -111,6 +117,7 @@ defmodule Membrane.Element.Base do
 
   Events may arrive from both input and output pads. In filters by default event is
   forwarded to all output and input pads, respectively.
+  By default, it ignores received event.
   """
   @callback handle_event(
               pad :: Pad.ref(),
@@ -131,6 +138,7 @@ defmodule Membrane.Element.Base do
 
   @doc """
   Callback invoked when a message from the parent is received.
+  By default, it ignores the received message.
   """
   @callback handle_parent_notification(
               notification :: Membrane.ParentNotification.t(),
@@ -141,7 +149,7 @@ defmodule Membrane.Element.Base do
   @doc """
   Callback invoked when element is removed by its parent.
 
-  By default it returns `t:Membrane.Element.Action.terminate/0` with reason `:normal`.
+  By default, it returns `t:Membrane.Element.Action.terminate/0` with reason `:normal`.
   """
   @callback handle_terminate_request(
               context :: CallbackContext.t(),

diff --git a/lib/membrane/pipeline.ex b/lib/membrane/pipeline.ex
@@ -103,14 +103,15 @@ defmodule Membrane.Pipeline do
   finishes. For that reason, it's important to do any long-lasting or complex work in `c:handle_setup/2`,
   while `handle_init` should be used for things like parsing options, initializing state or spawning
   children.
+  By default, it converts the `opts` to a map if they're a struct and sets them as the pipeline state.
   """
   @callback handle_init(context :: CallbackContext.t(), options :: pipeline_options) ::
               callback_return()
 
   @doc """
   Callback invoked when pipeline is requested to terminate with `terminate/2`.
 
-  By default it returns `t:Membrane.Pipeline.Action.terminate/0` with reason `:normal`.
+  By default, it returns `t:Membrane.Pipeline.Action.terminate/0` with reason `:normal`.
   """
   @callback handle_terminate_request(context :: CallbackContext.t(), state) ::
               callback_return()
@@ -119,6 +120,7 @@ defmodule Membrane.Pipeline do
   Callback invoked on pipeline startup, right after `c:handle_init/2`.
 
   Any long-lasting or complex initialization should happen here.
+  By default, it does nothing.
   """
   @callback handle_setup(
               context :: CallbackContext.t(),
@@ -128,6 +130,7 @@ defmodule Membrane.Pipeline do
 
   @doc """
   Callback invoked when pipeline switches the playback to `:playing`.
+  By default, it does nothing.
   """
   @callback handle_playing(
               context :: CallbackContext.t(),
@@ -141,6 +144,7 @@ defmodule Membrane.Pipeline do
   The callback won't be invoked, when you have initiated the pad removal,
   eg. when you have returned `t:Membrane.Pipeline.Action.remove_link()`
   action which made one of your children's pads be removed.
+  By default, it does nothing.
   """
   @callback handle_child_pad_removed(
               child :: Child.name(),
@@ -150,7 +154,9 @@ defmodule Membrane.Pipeline do
             ) :: callback_return
 
   @doc """
-  Callback invoked when a notification comes in from an element.
+  Callback invoked when a notification comes in from a child.
+
+  By default, it ignores the notification.
   """
   @callback handle_child_notification(
               notification :: Membrane.ChildNotification.t(),
@@ -164,6 +170,7 @@ defmodule Membrane.Pipeline do
   as an internal membrane message.
 
   Useful for receiving data sent from NIFs or other stuff.
+  By default, it ignores the received message.
   """
   @callback handle_info(
               message :: any,
@@ -174,6 +181,8 @@ defmodule Membrane.Pipeline do
 
   @doc """
   Callback invoked when a child element starts processing stream via given pad.
+
+  By default, it does nothing.
   """
   @callback handle_element_start_of_stream(
               child :: Child.name(),
@@ -184,6 +193,8 @@ defmodule Membrane.Pipeline do
 
   @doc """
   Callback invoked when a child element finishes processing stream via given pad.
+
+  By default, it does nothing.
   """
   @callback handle_element_end_of_stream(
               child :: Child.name(),
@@ -194,6 +205,8 @@ defmodule Membrane.Pipeline do
 
   @doc """
   Callback invoked when children of `Membrane.ChildrenSpec` are started.
+
+  By default, it does nothing.
   """
   @callback handle_spec_started(
               children :: [Child.name()],
@@ -215,6 +228,7 @@ defmodule Membrane.Pipeline do
   Callback invoked when crash of the crash group happens.
 
   Context passed to this callback contains 2 additional fields: `:members` and `:crash_initiator`.
+  By default, it does nothing.
   """
   @callback handle_crash_group_down(
               group_name :: Child.group(),
@@ -226,6 +240,7 @@ defmodule Membrane.Pipeline do
   Callback invoked when pipeline is called using a synchronous call.
 
   Context passed to this callback contains additional field `:from`.
+  By default, it does nothing.
   """
   @callback handle_call(
               message :: any,