From e840e77fb53e4f2ae657098d197557ce759d5e49 Mon Sep 17 00:00:00 2001 From: varsill Date: Mon, 8 May 2023 14:48:51 +0200 Subject: [PATCH 1/5] 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 """ From f5a21f0888fb1e0a205b7a6eda74504d9c652140 Mon Sep 17 00:00:00 2001 From: varsill Date: Mon, 8 May 2023 14:55:20 +0200 Subject: [PATCH 2/5] Improve ComponentPath moduledoc --- lib/membrane/component_path.ex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/membrane/component_path.ex b/lib/membrane/component_path.ex index e97de6b81..7ef0cfe1b 100644 --- a/lib/membrane/component_path.ex +++ b/lib/membrane/component_path.ex @@ -1,9 +1,9 @@ defmodule Membrane.ComponentPath do @moduledoc """ - 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. + A list consisting of following pipeline/bin/element names down the assembled pipeline. It traces element's path inside a pipeline. + Information is being stored in a process dictionary and can be set/appended to. """ @typedoc @moduledoc From 0d33acec2efa75614b2bee9befb6a338ef8297d7 Mon Sep 17 00:00:00 2001 From: varsill Date: Mon, 8 May 2023 14:57:20 +0200 Subject: [PATCH 3/5] Improve typedocs for protocols --- lib/membrane/event_protocol.ex | 2 +- lib/membrane/payload.ex | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/lib/membrane/event_protocol.ex b/lib/membrane/event_protocol.ex index 7d1b7b4a9..d100350f8 100644 --- a/lib/membrane/event_protocol.ex +++ b/lib/membrane/event_protocol.ex @@ -6,7 +6,7 @@ defprotocol Membrane.EventProtocol do """ @typedoc """ - A type describing all the types that implement the `Membrane.EventProtocol`. + A type describing all the types that implement the `Membrane.EventProtocol` protocol. """ @type t :: struct diff --git a/lib/membrane/payload.ex b/lib/membrane/payload.ex index 1fa0d9e22..c00e9c67b 100644 --- a/lib/membrane/payload.ex +++ b/lib/membrane/payload.ex @@ -24,7 +24,7 @@ defprotocol Membrane.Payload do end @typedoc """ - A type describing all the types that are implementing `Membrane.Payload` protocol. + A type describing all the types that implement `Membrane.Payload` protocol. """ @type t :: any() From 0e091559e3577251ef8fce2ae6a1d23f04398a89 Mon Sep 17 00:00:00 2001 From: varsill Date: Tue, 9 May 2023 09:35:27 +0200 Subject: [PATCH 4/5] Implement reviewers suggestions --- lib/membrane/time.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/membrane/time.ex b/lib/membrane/time.ex index 9373e50bd..4e11a529f 100644 --- a/lib/membrane/time.ex +++ b/lib/membrane/time.ex @@ -17,7 +17,7 @@ defmodule Membrane.Time do 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. + The time represented in Membrane's native time units. """ @type t :: integer @type non_neg :: non_neg_integer From ec7551403621dbcf487f1faabbd9515ed01f7e1e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C5=81ukasz=20Kita?= Date: Thu, 11 May 2023 10:13:32 +0200 Subject: [PATCH 5/5] Update lib/membrane/time.ex Co-authored-by: Mateusz Front --- lib/membrane/time.ex | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/lib/membrane/time.ex b/lib/membrane/time.ex index 4e11a529f..798247939 100644 --- a/lib/membrane/time.ex +++ b/lib/membrane/time.ex @@ -17,7 +17,7 @@ defmodule Membrane.Time do native_units: 1, native_unit: 0, nanoseconds: 1, nanosecond: 0, second: 0, seconds: 1} @typedoc """ - The time represented in Membrane's native time units. + The time represented in Membrane's time units. """ @type t :: integer @type non_neg :: non_neg_integer