From cfbe641e61b83f0a8c3865d1877588d04a04bf1a Mon Sep 17 00:00:00 2001
From: Stefan Chrobot <stefan@chrobot.io>
Date: Mon, 13 Dec 2021 12:42:15 +0100
Subject: [PATCH] Update documentation for span/3 (#101)

---
 src/telemetry.erl | 14 ++++++++------
 1 file changed, 8 insertions(+), 6 deletions(-)

diff --git a/src/telemetry.erl b/src/telemetry.erl
index 41dde99..5ed28cf 100644
--- a/src/telemetry.erl
+++ b/src/telemetry.erl
@@ -176,7 +176,9 @@ execute(EventName, Measurements, Metadata) when is_map(Measurements) and is_map(
         end,
     lists:foreach(ApplyFun, Handlers).
 
-%% @doc Emit start, and stop/exception events, invoking the handlers attached to each.
+%% @doc Runs the provided `SpanFunction', emitting start and stop/exception events, invoking the handlers attached to each.
+%%
+%% The `SpanFunction' must return a `{result, stop_metadata}' tuple.
 %%
 %% When this function is called, 2 events will be emitted via {@link execute/3}. Those events will be one of the following
 %% pairs:
@@ -185,7 +187,7 @@ execute(EventName, Measurements, Metadata) when is_map(Measurements) and is_map(
 %% <li>`EventPrefix ++ [start]' and `EventPrefix ++ [exception]'</li>
 %% </ul>
 %%
-%% However, note that in case the current processes crashes due to an exit signal
+%% However, note that in case the current process crashes due to an exit signal
 %% of another process, then none or only part of those events would be emitted.
 %% Below is a breakdown of the measurements and metadata associated with each individual event.
 %%
@@ -226,7 +228,7 @@ execute(EventName, Measurements, Metadata) when is_map(Measurements) and is_map(
 %% ```
 %% #{
 %%   telemetry_span_context => term(),
-%%   % User defined metadata
+%%   % User defined metadata as provided in StartMetadata
 %%   ...
 %% }
 %% '''
@@ -259,10 +261,10 @@ execute(EventName, Measurements, Metadata) when is_map(Measurements) and is_map(
 %% ```
 %% #{
 %%   % An optional error field if the stop event is the result of an error
-%%   % but not necessarily an exception. Additional user defined metadata can
-%%   % also be added here.
+%%   % but not necessarily an exception.
 %%   error => term(),
 %%   telemetry_span_context => term(),
+%%   % User defined metadata as provided in StopMetadata
 %%   ...
 %% }
 %% '''
@@ -298,7 +300,7 @@ execute(EventName, Measurements, Metadata) when is_map(Measurements) and is_map(
 %%   reason => term(),
 %%   stacktrace => list(),
 %%   telemetry_span_context => term(),
-%%   % User defined metadata from the start event
+%%   % User defined metadata as provided in StartMetadata
 %%    ...
 %% }
 %% '''