From e840e77fb53e4f2ae657098d197557ce759d5e49 Mon Sep 17 00:00:00 2001
From: varsill <lukasz.kita0@gmail.com>
Date: Mon, 8 May 2023 14:48:51 +0200
Subject: [PATCH] Add typedocs

---
 lib/membrane/bin/pad_data.ex           |  1 +
 lib/membrane/buffer.ex                 |  1 +
 lib/membrane/child_entry.ex            |  1 +
 lib/membrane/clock.ex                  |  1 +
 lib/membrane/component_path.ex         |  6 ++++--
 lib/membrane/element/pad_data.ex       |  1 +
 lib/membrane/event.ex                  |  1 +
 lib/membrane/event/discontinuity.ex    |  1 +
 lib/membrane/event/underrun.ex         |  2 ++
 lib/membrane/event_protocol.ex         |  3 +++
 lib/membrane/keyframe_request_event.ex |  1 +
 lib/membrane/notification.ex           |  3 ++-
 lib/membrane/payload.ex                |  3 +++
 lib/membrane/playback.ex               |  2 ++
 lib/membrane/rc_message.ex             | 13 +++++++++++++
 lib/membrane/remote_stream.ex          |  2 ++
 lib/membrane/resource_guard.ex         |  3 +++
 lib/membrane/stream_format.ex          |  2 ++
 lib/membrane/sync.ex                   |  4 ++++
 lib/membrane/time.ex                   |  3 +++
 lib/membrane/utility_supervisor.ex     |  4 ++++
 21 files changed, 55 insertions(+), 3 deletions(-)

diff --git a/lib/membrane/bin/pad_data.ex b/lib/membrane/bin/pad_data.ex
index 905277481..988810fc4 100644
--- a/lib/membrane/bin/pad_data.ex
+++ b/lib/membrane/bin/pad_data.ex
@@ -16,6 +16,7 @@ defmodule Membrane.Bin.PadData do
 
   @type private_field :: term()
 
+  @typedoc @moduledoc
   @type t :: %__MODULE__{
           ref: Membrane.Pad.ref(),
           options: Membrane.ChildrenSpec.pad_options(),
diff --git a/lib/membrane/buffer.ex b/lib/membrane/buffer.ex
index 57cdedfe3..0a2954ce4 100644
--- a/lib/membrane/buffer.ex
+++ b/lib/membrane/buffer.ex
@@ -13,6 +13,7 @@ defmodule Membrane.Buffer do
 
   @type metadata :: map
 
+  @typedoc @moduledoc
   @type t :: %Buffer{
           pts: Time.t() | nil,
           dts: Time.t() | nil,
diff --git a/lib/membrane/child_entry.ex b/lib/membrane/child_entry.ex
index d8fa8f032..5b28c513e 100644
--- a/lib/membrane/child_entry.ex
+++ b/lib/membrane/child_entry.ex
@@ -13,6 +13,7 @@ defmodule Membrane.ChildEntry do
   """
   use Bunch.Access
 
+  @typedoc @moduledoc
   @type t :: %__MODULE__{
           name: Membrane.Child.name(),
           module: module,
diff --git a/lib/membrane/clock.ex b/lib/membrane/clock.ex
index 32083ca86..bc42e406f 100644
--- a/lib/membrane/clock.ex
+++ b/lib/membrane/clock.ex
@@ -32,6 +32,7 @@ defmodule Membrane.Clock do
   alias Membrane.Core.Message
   alias Membrane.Time
 
+  @typedoc @moduledoc
   @type t :: pid
 
   @typedoc """
diff --git a/lib/membrane/component_path.ex b/lib/membrane/component_path.ex
index 3d9a3d79f..e97de6b81 100644
--- a/lib/membrane/component_path.ex
+++ b/lib/membrane/component_path.ex
@@ -1,10 +1,12 @@
 defmodule Membrane.ComponentPath do
   @moduledoc """
-  Traces element's path inside a pipeline.
-  Path is a list consisted of following pipeline/bin/element names down the assembled pipeline.
+  Path is a list consisting of following pipeline/bin/element names down the assembled pipeline.
   Information is being stored in a process dictionary and can be set/appended to.
+
+  It traces element's path inside a pipeline.
   """
 
+  @typedoc @moduledoc
   @type path :: list(String.t())
 
   @key :membrane_path
diff --git a/lib/membrane/element/pad_data.ex b/lib/membrane/element/pad_data.ex
index c3fc6b72d..2186313d3 100644
--- a/lib/membrane/element/pad_data.ex
+++ b/lib/membrane/element/pad_data.ex
@@ -24,6 +24,7 @@ defmodule Membrane.Element.PadData do
 
   @type private_field :: term()
 
+  @typedoc @moduledoc
   @type t :: %__MODULE__{
           availability: Pad.availability(),
           stream_format: StreamFormat.t() | nil,
diff --git a/lib/membrane/event.ex b/lib/membrane/event.ex
index 5d2d36cef..2ed7405b6 100644
--- a/lib/membrane/event.ex
+++ b/lib/membrane/event.ex
@@ -10,6 +10,7 @@ defmodule Membrane.Event do
 
   alias Membrane.EventProtocol
 
+  @typedoc @moduledoc
   @type t :: EventProtocol.t()
 
   @spec event?(t()) :: boolean
diff --git a/lib/membrane/event/discontinuity.ex b/lib/membrane/event/discontinuity.ex
index 303ea8b36..f846e32e4 100644
--- a/lib/membrane/event/discontinuity.ex
+++ b/lib/membrane/event/discontinuity.ex
@@ -16,5 +16,6 @@ defmodule Membrane.Event.Discontinuity do
 
   defstruct duration: nil
 
+  @typedoc @moduledoc
   @type t :: %__MODULE__{duration: duration}
 end
diff --git a/lib/membrane/event/underrun.ex b/lib/membrane/event/underrun.ex
index 619f27cbb..4288f1711 100644
--- a/lib/membrane/event/underrun.ex
+++ b/lib/membrane/event/underrun.ex
@@ -10,5 +10,7 @@ defmodule Membrane.Event.Underrun do
   """
   @derive Membrane.EventProtocol
   defstruct []
+
+  @typedoc @moduledoc
   @type t :: %__MODULE__{}
 end
diff --git a/lib/membrane/event_protocol.ex b/lib/membrane/event_protocol.ex
index ad5af10c8..7d1b7b4a9 100644
--- a/lib/membrane/event_protocol.ex
+++ b/lib/membrane/event_protocol.ex
@@ -5,6 +5,9 @@ defprotocol Membrane.EventProtocol do
   Each event has to implement or derive this protocol.
   """
 
+  @typedoc """
+  A type describing all the types that implement the `Membrane.EventProtocol`.
+  """
   @type t :: struct
 
   @doc """
diff --git a/lib/membrane/keyframe_request_event.ex b/lib/membrane/keyframe_request_event.ex
index abb153fc9..92cd69a2d 100644
--- a/lib/membrane/keyframe_request_event.ex
+++ b/lib/membrane/keyframe_request_event.ex
@@ -11,5 +11,6 @@ defmodule Membrane.KeyframeRequestEvent do
 
   defstruct []
 
+  @typedoc @moduledoc
   @type t :: %__MODULE__{}
 end
diff --git a/lib/membrane/notification.ex b/lib/membrane/notification.ex
index 196a152c1..3a308ad43 100644
--- a/lib/membrane/notification.ex
+++ b/lib/membrane/notification.ex
@@ -8,6 +8,7 @@ defmodule Membrane.ChildNotification do
   `c:Membrane.Parent.handle_child_notification/4` callback.
   """
 
+  @typedoc @moduledoc
   @type t :: any
 end
 
@@ -20,6 +21,6 @@ defmodule Membrane.ParentNotification do
   A notification can be handled in child with `c:Membrane.Element.Base.handle_parent_notification/3` or
   `c:Membrane.Bin.handle_parent_notification/3` callback.
   """
-
+  @typedoc @moduledoc
   @type t :: any
 end
diff --git a/lib/membrane/payload.ex b/lib/membrane/payload.ex
index 2b841c0f6..1fa0d9e22 100644
--- a/lib/membrane/payload.ex
+++ b/lib/membrane/payload.ex
@@ -23,6 +23,9 @@ defprotocol Membrane.Payload do
     @callback new(binary()) :: Membrane.Payload.t()
   end
 
+  @typedoc """
+  A type describing all the types that are implementing `Membrane.Payload` protocol.
+  """
   @type t :: any()
 
   @doc """
diff --git a/lib/membrane/playback.ex b/lib/membrane/playback.ex
index a348f4649..a2d07bb66 100644
--- a/lib/membrane/playback.ex
+++ b/lib/membrane/playback.ex
@@ -12,5 +12,7 @@ defmodule Membrane.Playback do
 
   Untils the setup lasts, the component won't enter `:playing` playback.
   """
+
+  @typedoc @moduledoc
   @type t :: :stopped | :playing
 end
diff --git a/lib/membrane/rc_message.ex b/lib/membrane/rc_message.ex
index 4fd792fa9..7d09889d2 100644
--- a/lib/membrane/rc_message.ex
+++ b/lib/membrane/rc_message.ex
@@ -5,6 +5,9 @@ defmodule Membrane.RCMessage do
   Check `t:t/0` for available messages.
   """
 
+  @typedoc """
+  The type describing all possible `Membrane.RCMessage`s.
+  """
   @type t ::
           __MODULE__.Playing.t()
           | __MODULE__.StartOfStream.t()
@@ -16,6 +19,8 @@ defmodule Membrane.RCMessage do
     @moduledoc """
     Message sent when the pipeline starts playing
     """
+
+    @typedoc @moduledoc
     @type t :: %__MODULE__{from: pid()}
 
     @enforce_keys [:from]
@@ -26,6 +31,8 @@ defmodule Membrane.RCMessage do
     @moduledoc """
     Message sent when some element of the pipeline receives the start of stream event on some pad.
     """
+
+    @typedoc @moduledoc
     @type t :: %__MODULE__{
             from: pid(),
             element: Membrane.Element.name(),
@@ -40,6 +47,8 @@ defmodule Membrane.RCMessage do
     @moduledoc """
     Message sent when some element of the pipeline receives the start of stream event on some pad.
     """
+
+    @typedoc @moduledoc
     @type t :: %__MODULE__{
             from: pid(),
             element: Membrane.Element.name(),
@@ -54,6 +63,8 @@ defmodule Membrane.RCMessage do
     @moduledoc """
     Message sent when the some element of the pipeline receives a notification.
     """
+
+    @typedoc @moduledoc
     @type t :: %__MODULE__{
             from: pid(),
             element: Membrane.Element.name(),
@@ -68,6 +79,8 @@ defmodule Membrane.RCMessage do
     @moduledoc """
     Message sent when the pipeline gracefully terminates.
     """
+
+    @typedoc @moduledoc
     @type t :: %__MODULE__{from: pid()}
 
     @enforce_keys [:from]
diff --git a/lib/membrane/remote_stream.ex b/lib/membrane/remote_stream.ex
index 429002206..d09c9f2cd 100644
--- a/lib/membrane/remote_stream.ex
+++ b/lib/membrane/remote_stream.ex
@@ -11,6 +11,8 @@ defmodule Membrane.RemoteStream do
   - `:type` - either `:bytestream` (continuous stream) or `:packetized` (each buffer
   contains exactly one specified unit of data)
   """
+
+  @typedoc @moduledoc
   @type t :: %__MODULE__{
           content_format: module | nil,
           type: :bytestream | :packetized
diff --git a/lib/membrane/resource_guard.ex b/lib/membrane/resource_guard.ex
index 875a9a676..c738738c7 100644
--- a/lib/membrane/resource_guard.ex
+++ b/lib/membrane/resource_guard.ex
@@ -24,6 +24,9 @@ defmodule Membrane.ResourceGuard do
   require Membrane.Core.Message, as: Message
   require Membrane.Logger
 
+  @typedoc """
+  Utility for handling resources that must be cleaned up after use
+  """
   @type t :: pid()
 
   @spec start_link(owner_pid :: pid) :: {:ok, t}
diff --git a/lib/membrane/stream_format.ex b/lib/membrane/stream_format.ex
index 0bc45a30b..f003f2448 100644
--- a/lib/membrane/stream_format.ex
+++ b/lib/membrane/stream_format.ex
@@ -8,5 +8,7 @@ defmodule Membrane.StreamFormat do
 
   To link two pads together, their capabilities have to be compatible.
   """
+
+  @typedoc @moduledoc
   @type t :: struct
 end
diff --git a/lib/membrane/sync.ex b/lib/membrane/sync.ex
index c0fc7e1a3..f3f797357 100644
--- a/lib/membrane/sync.ex
+++ b/lib/membrane/sync.ex
@@ -33,6 +33,10 @@ defmodule Membrane.Sync do
 
   @no_sync :membrane_no_sync
 
+  @typedoc """
+  A type describing the the synchronization mechanism, used to synchronize multiple
+  processes, so that they could perform their jobs at the same time.
+  """
   @type t :: pid | :membrane_no_sync
   @type status :: :registered | :sync
 
diff --git a/lib/membrane/time.ex b/lib/membrane/time.ex
index 50e178477..9373e50bd 100644
--- a/lib/membrane/time.ex
+++ b/lib/membrane/time.ex
@@ -16,6 +16,9 @@ defmodule Membrane.Time do
   @compile {:inline,
             native_units: 1, native_unit: 0, nanoseconds: 1, nanosecond: 0, second: 0, seconds: 1}
 
+  @typedoc """
+  The time represented in Membrane's native time units - nanoseconds.
+  """
   @type t :: integer
   @type non_neg :: non_neg_integer
 
diff --git a/lib/membrane/utility_supervisor.ex b/lib/membrane/utility_supervisor.ex
index ef95a5a8d..c826a7f07 100644
--- a/lib/membrane/utility_supervisor.ex
+++ b/lib/membrane/utility_supervisor.ex
@@ -17,6 +17,10 @@ defmodule Membrane.UtilitySupervisor do
       end
 
   """
+
+  @typedoc """
+  The pid of the `Membrane.UtilitySupervisor` process.
+  """
   @type t :: pid()
 
   @doc """