Merge pull request #821 from msutkowski/ms/add-spec-links

chore: add relevant links to spec in doc blocks

Author: tsloughter

README.md

@@ -86,7 +86,7 @@ default implementation of the API that must be optional.
 
 When instrumenting a project, your application should only depend on the
 [OpenTelemetry API](https://hex.pm/packages/opentelemetry_api) application,
-found in directory `apps/opentelemetry_api` of this repo.  The API is published as
+found in directory `apps/opentelemetry_api` of this repo. The API is published as
 the Hex package [opentelemetry_api](https://hex.pm/packages/opentelemetry_api).
 
 The SDK implementation, found under `apps/opentelemetry` and Hex package
@@ -95,7 +95,7 @@ OTP Release along with an exporter.
 
 Example of Release configuration in `rebar.config`:
 
-``` erlang
+```erlang
 {relx, [{release, {my_instrumented_release, "0.1.0"},
          [opentelemetry_exporter,
 	      {opentelemetry, temporary},
@@ -107,7 +107,7 @@ Example of Release configuration in `rebar.config`:
 Example configuration for [mix's Release
 task](https://hexdocs.pm/mix/Mix.Tasks.Release.html):
 
-``` elixir
+```elixir
 def project do
   [
     releases: [
@@ -121,14 +121,14 @@ def project do
 end
 ```
 
-Note that you also need  to add `opentelemetry_exporter` before your other `opentelemetry` dependencies in `mix.exs`,
+Note that you also need to add `opentelemetry_exporter` before your other `opentelemetry` dependencies in `mix.exs`,
 so that it starts before `opentelemetry` does.
 
 In the above example `opentelemetry_exporter` is listed first, ensuring that all of its
 dependencies are booted before `opentelemetry` attempts to start the
 exporter. `opentelemetry` is set to `temporary` so that if the `opentelemetry`
 application crashes, or is shutdown, it does not terminate the other
-applications in the project -- `opentelemetry_exporter` does not not need to be
+applications in the project -- `opentelemetry_exporter` does not need to be
 `temporary` because it does not have a startup and supervision tree. This is
 optional; the `opentelemetry` application purposely sticks to `permanent` for
 the processes started by the root supervisor to leave it up to the end user
@@ -149,14 +149,13 @@ Applications are kept in a single repository, under the directory `apps`, either
 blocks below show how the git repo for the API and/or SDK
 Applications can be used in rebar3 and mix.
 
-``` erlang
+```erlang
 {opentelemetry_api, {git_subdir, "http://github.com/open-telemetry/opentelemetry-erlang", {branch, "main"}, "apps/opentelemetry_api"}},
-{opentelemetry, {git_subdir, "http://github.com/open-telemetry/opentelemetry-erlang", {branch, "main"},
-"apps/opentelemetry"}},
+{opentelemetry, {git_subdir, "http://github.com/open-telemetry/opentelemetry-erlang", {branch, "main"}, "apps/opentelemetry"}},
 {opentelemetry_exporter, {git_subdir, "http://github.com/open-telemetry/opentelemetry-erlang", {branch, "main"}, "apps/opentelemetry_exporter"}}
 ```
 
-``` elixir
+```elixir
 {:opentelemetry_api, github: "open-telemetry/opentelemetry-erlang", sparse:
 "apps/opentelemetry_api", override: true},
 {:opentelemetry, github: "open-telemetry/opentelemetry-erlang", sparse:
@@ -175,7 +174,7 @@ it is included the override is necessary.
 
 Running benchmarks is done with [benchee](https://github.com/bencheeorg/benchee). Benchmark functions are stored in modules, under `samples/`. To run them, open a rebar3 shell in the `bench` profile:
 
-``` shell
+```shell
 $ rebar3 as bench shell
 
 > otel_benchmarks:run().
@@ -184,23 +183,23 @@ $ rebar3 as bench shell
 If an Elixir script is wanted for the benchmarks they could be run (after
 running `rebar3 as bench compile`) as follows:
 
-``` shell
+```shell
 $ ERL_AFLAGS="-pa ./_build/bench/extras/samples/" ERL_LIBS=_build/bench/lib/ mix run --no-mix-exs samples/run.exs
 ```
 
 ## W3C Trace Context Interop Tests
 
 Start the interop web server in a shell:
 
-``` shell
+```shell
 $ rebar3 as interop shell
 
 > w3c_trace_context_interop:start().
 ```
 
 Then, clone the [W3C Trace Context repo](https://github.com/w3c/trace-context) and run the tests:
 
-``` shell
+```shell
 $ cd test
 $ python3 test.py http://127.0.0.1:5000/test
 ```
@@ -216,7 +215,7 @@ Approvers ([@open-telemetry/erlang-approvers](https://github.com/orgs/open-telem
 - [Łukasz Jan Niemier](https://github.com/hauleth)
 - [Iliia Khaprov](https://github.com/deadtrickster), [VMWare](https://www.vmware.com/)
 
-*Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver).*
+_Find more about the approver role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#approver)._
 
 Maintainers ([@open-telemetry/erlang-maintainers](https://github.com/orgs/open-telemetry/teams/erlang-maintainers)):
 
@@ -225,7 +224,7 @@ Maintainers ([@open-telemetry/erlang-maintainers](https://github.com/orgs/open-t
 - [Łukasz Jan Niemier](https://github.com/hauleth)
 - [Iliia Khaprov](https://github.com/deadtrickster), [VMWare](https://www.vmware.com/)
 
-*Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer).*
+_Find more about the maintainer role in [community repository](https://github.com/open-telemetry/community/blob/master/community-membership.md#maintainer)._
 
 ### Thanks to all the people who have contributed
 

apps/opentelemetry_api/lib/open_telemetry/span.ex

@@ -27,6 +27,8 @@ defmodule OpenTelemetry.Span do
   - A list of Links to other Spans (`t:OpenTelemetry.link/0`)
   - A list of timestamped Events (`t:OpenTelemetry.event/0`)
   - A Status (`t:OpenTelemetry.status/0`)
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#span)
   """
 
   @type start_opts() :: :otel_span.start_opts()
@@ -67,6 +69,8 @@ defmodule OpenTelemetry.Span do
   child Spans that may exist of this Span.
 
   The Span Context is returned with `is_recording` set to `false`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#end)
   """
   defdelegate end_span(span_ctx), to: :otel_span
 
@@ -75,21 +79,29 @@ defmodule OpenTelemetry.Span do
   child Spans that may exist of this Span.
 
   The Span Context is returned with `is_recording` set to `false`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#end)
   """
   defdelegate end_span(span_ctx, timestamp), to: :otel_span
 
   @doc """
+  Returns whether this Span is recording information like events, attributes, status, etc.
 
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#isrecording)
   """
   defdelegate is_recording(span_ctx), to: :otel_span
 
   @doc """
+  Returns true if the SpanContext has a non-zero TraceId and SpanId.
 
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#isvalid)
   """
   defdelegate is_valid(span_ctx), to: :otel_span
 
   @doc """
   Set an attribute with key and value on the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-attributes)
   """
   @spec set_attribute(
           OpenTelemetry.span_ctx(),
@@ -100,12 +112,16 @@ defmodule OpenTelemetry.Span do
 
   @doc """
   Add a list of attributes to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-attributes)
   """
   @spec set_attributes(OpenTelemetry.span_ctx(), OpenTelemetry.attributes_map()) :: boolean()
   defdelegate set_attributes(span_ctx, attributes), to: :otel_span
 
   @doc """
   Add an event to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#add-events)
   """
   @spec add_event(
           OpenTelemetry.span_ctx(),
@@ -116,6 +132,8 @@ defmodule OpenTelemetry.Span do
 
   @doc """
   Add a list of events to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#add-events)
   """
   @spec add_events(OpenTelemetry.span_ctx(), [OpenTelemetry.event()]) :: boolean()
   defdelegate add_events(span_ctx, events), to: :otel_span
@@ -130,6 +148,8 @@ defmodule OpenTelemetry.Span do
   Record an exception as an event, following the semantics convetions for exceptions.
 
   If trace is not provided, the stacktrace is retrieved from `Process.info/2`
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#record-exception)
   """
   @spec record_exception(OpenTelemetry.span_ctx(), Exception.t()) :: boolean()
   def record_exception(span_ctx, exception, trace \\ nil, attributes \\ [])
@@ -154,6 +174,8 @@ defmodule OpenTelemetry.Span do
   If used, this will override the default Span Status, which is `:unset`.
   Valid statuses are `:ok`, or `:error`. Calling this will also set the
   `status_code` attribute to `1`(`:ok`), or `2`(`:error`).
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-status)
   """
   @spec set_status(OpenTelemetry.span_ctx(), OpenTelemetry.status()) :: boolean()
   defdelegate set_status(span_ctx, status), to: :otel_span
@@ -166,10 +188,12 @@ defmodule OpenTelemetry.Span do
   logic will be implemented before the Span creation for performance reasons. Thus the name
   update may interfere with this logic.
 
-  The function name is called UpdateName to differentiate this function from the regular
+  The function name is called update_name to differentiate this function from the regular
   property setter. It emphasizes that this operation signifies a major change for a Span
   and may lead to re-calculation of sampling or filtering decisions made previously
   depending on the implementation.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#updatename)
   """
   @spec update_name(OpenTelemetry.span_ctx(), OpenTelemetry.span_name()) :: boolean()
   defdelegate update_name(span_ctx, name), to: :otel_span

apps/opentelemetry_api/lib/open_telemetry/tracer.ex

@@ -14,12 +14,16 @@ defmodule OpenTelemetry.Tracer do
       Tracer.with_span "span-1" do
         ... do something ...
       end
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#tracer)
   """
 
   @doc """
   Starts a new span and does not make it the current active span of the current process.
 
   The current active Span is used as the parent of the created Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#span-creation)
   """
   defmacro start_span(name, opts \\ quote(do: %{})) do
     quote bind_quoted: [name: name, start_opts: opts] do
@@ -35,6 +39,8 @@ defmodule OpenTelemetry.Tracer do
   Starts a new span and does not make it the current active span of the current process.
 
   The current active Span is used as the parent of the created Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#span-creation)
   """
   defmacro start_span(ctx, name, opts) do
     quote bind_quoted: [ctx: ctx, name: name, start_opts: opts] do
@@ -49,6 +55,8 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Takes a `t:OpenTelemetry.span_ctx/0` and the Tracer sets it to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#get-context)
   """
   def set_current_span(span_ctx) do
     :otel_tracer.set_current_span(span_ctx)
@@ -57,6 +65,8 @@ defmodule OpenTelemetry.Tracer do
   @doc """
   Takes a `t:OpenTelemetry.Ctx.t/0` and the `t:OpenTelemetry.span_ctx/0` and the Tracer sets
   it to the current span in the pass Context.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#get-context)
   """
   def set_current_span(ctx, span_ctx) do
     :otel_tracer.set_current_span(ctx, span_ctx)
@@ -68,6 +78,8 @@ defmodule OpenTelemetry.Tracer do
   before the block.
 
   See `start_span/2` and `end_span/0`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#span-creation)
   """
   defmacro with_span(name, start_opts \\ quote(do: %{}), do: block) do
     quote do
@@ -86,6 +98,8 @@ defmodule OpenTelemetry.Tracer do
   before the block.
 
   See `start_span/2` and `end_span/0`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#span-creation)
   """
   defmacro with_span(ctx, name, start_opts, do: block) do
     quote do
@@ -101,13 +115,17 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Returns the currently active `t:OpenTelemetry.span_ctx/0`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#get-context)
   """
   def current_span_ctx() do
     :otel_tracer.current_span_ctx()
   end
 
   @doc """
   Returns the `t:OpenTelemetry.span_ctx/0` active in Context `ctx`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#get-context)
   """
   def current_span_ctx(ctx) do
     :otel_tracer.current_span_ctx(ctx)
@@ -120,6 +138,8 @@ defmodule OpenTelemetry.Tracer do
   To end a specific span, see `OpenTelemetry.Span.end_span/1`.
 
   The Span in the current Context has its `is_recording` set to `false`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#end)
   """
   @spec end_span(:opentelemetry.timestamp() | :undefined) ::
           :opentelemetry.span_ctx() | :undefined
@@ -131,6 +151,8 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Set an attribute with key and value on the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-attributes)
   """
   @spec set_attribute(OpenTelemetry.attribute_key(), OpenTelemetry.attribute_value()) :: boolean()
   def set_attribute(key, value) do
@@ -143,6 +165,8 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Add a list of attributes to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-attributes)
   """
   @spec set_attributes(OpenTelemetry.attributes_map()) :: boolean()
   def set_attributes(attributes) do
@@ -151,6 +175,8 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Add an event to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#add-events)
   """
   @spec add_event(OpenTelemetry.event_name(), OpenTelemetry.attributes_map()) :: boolean()
   def add_event(event, attributes) do
@@ -163,6 +189,8 @@ defmodule OpenTelemetry.Tracer do
 
   @doc """
   Add a list of events to the currently active Span.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#add-events)
   """
   @spec add_events([OpenTelemetry.event()]) :: boolean()
   def add_events(events) do
@@ -173,6 +201,8 @@ defmodule OpenTelemetry.Tracer do
   Record an exception as an event, following the semantics convetions for exceptions.
 
   If trace is not provided, the stacktrace is retrieved from `Process.info/2`
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#record-exception)
   """
   @spec record_exception(Exception.t()) :: boolean()
   def record_exception(exception, trace \\ nil, attributes \\ []) do
@@ -188,6 +218,8 @@ defmodule OpenTelemetry.Tracer do
   Creates and sets the Status of the currently active Span.
 
   If used, this will override the default Span Status, which is `:unset`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-status)
   """
   @spec set_status(OpenTelemetry.status_code(), String.t()) :: boolean()
   def set_status(code, message) do
@@ -198,6 +230,8 @@ defmodule OpenTelemetry.Tracer do
   Sets the Status of the currently active Span.
 
   If used, this will override the default Span Status, which is `:unset`.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#set-status)
   """
   @spec set_status(OpenTelemetry.status()) :: boolean()
   def set_status(status) do
@@ -212,10 +246,12 @@ defmodule OpenTelemetry.Tracer do
   logic will be implemented before the Span creation for performance reasons. Thus the name
   update may interfere with this logic.
 
-  The function name is called UpdateName to differentiate this function from the regular
+  The function name is called update_name to differentiate this function from the regular
   property setter. It emphasizes that this operation signifies a major change for a Span
   and may lead to re-calculation of sampling or filtering decisions made previously
   depending on the implementation.
+
+  See [specification](https://github.com/open-telemetry/opentelemetry-specification/blob/v1.8.0/specification/trace/api.md#updatename)
   """
   @spec update_name(String.t()) :: boolean()
   def update_name(name) do