Various doc improvements (#453)

* Various doc improvements

* Update lib/new_relic.ex

---------

Co-authored-by: Vince Foley <[email protected]>

Author: axelson

lib/new_relic.ex

@@ -9,7 +9,7 @@ defmodule NewRelic do
   The first segment will be treated as the Transaction namespace,
   and commonly contains the name of the framework.
 
-  **Notes:**
+  ## Notes
   * At least 2 segments are required to light up the Transactions UI in APM
 
   In the following example, you will see `/custom/transaction/name`
@@ -43,7 +43,7 @@ defmodule NewRelic do
     # "list.length" => 3
   ```
 
-  **Notes:**
+  ## Notes
   * Nested Lists and Maps are truncated at 10 items since there are a limited number
   of attributes that can be reported on Transaction events
   """
@@ -59,23 +59,26 @@ defmodule NewRelic do
   (ie: Not a "Web" Transaction). The first argument will be considered
   the "category", the second is the "name".
 
-  Examples:
+  ## Examples
 
   ```elixir
   NewRelic.start_transaction("GenStage", "MyConsumer/EventType")
   NewRelic.start_transaction("Task", "TaskName")
   ```
 
-  **Notes:**
+  > #### Warning {: .error}
+  >
+  > * You can't start a new transaction within an existing one. Any process
+  > spawned inside a transaction belongs to that transaction.
+  > * Do _not_ use this for processes that live a very long time, doing so
+  > will risk a memory leak tracking attributes in the transaction!
+
+  ## Notes
 
   * Don't use this to track Web Transactions - Plug based HTTP servers
   are auto-instrumented based on `telemetry` events.
-  * Do _not_ use this for processes that live a very long time, doing so
-  will risk a memory leak tracking attributes in the transaction!
-  * You can't start a new transaction within an existing one. Any process
-  spawned inside a transaction belongs to that transaction.
   * If multiple transactions are started in the same Process, you must
-  call `NewRelic.stop_transaction()` to mark the end of the transaction.
+  call `NewRelic.stop_transaction/0` to mark the end of the transaction.
   """
   @spec start_transaction(String.t(), String.t()) :: :ok
   defdelegate start_transaction(category, name), to: NewRelic.OtherTransaction
@@ -84,7 +87,7 @@ defmodule NewRelic do
   Stop an "Other" Transaction.
 
   If multiple transactions are started in the same Process, you must
-  call `NewRelic.stop_transaction()` to mark the end of the transaction.
+  call `NewRelic.stop_transaction/0` to mark the end of the transaction.
   """
   @spec stop_transaction() :: :ok
   defdelegate stop_transaction(), to: NewRelic.OtherTransaction
@@ -93,10 +96,10 @@ defmodule NewRelic do
   Define an "Other" transaction with the given block. The return value of
   the block is returned.
 
-  See `start_transaction` and `stop_transaction` for more details about
+  See `start_transaction/2` and `stop_transaction/0` for more details about
   Transactions.
 
-  Example:
+  ## Example
 
   ```elixir
   defmodule Worker do
@@ -122,6 +125,8 @@ defmodule NewRelic do
   @doc """
   Call within a transaction to prevent it from reporting.
 
+  ## Example
+
   ```elixir
   def index(conn, _) do
     NewRelic.ignore_transaction()
@@ -139,20 +144,20 @@ defmodule NewRelic do
   @doc """
   Advanced:
   Return a Transaction reference that can be used to manually connect a
-  process to a Transaction with `NewRelic.connect_to_transaction()`
+  process to a Transaction with `NewRelic.connect_to_transaction/1`
   """
   defdelegate get_transaction(), to: NewRelic.Transaction.Reporter
 
   @doc """
   Advanced:
   Call to manually connect the current process to a Transaction. Pass in a reference
-  returned by `NewRelic.get_transaction()`
+  returned by `NewRelic.get_transaction/0`
 
   Only use this when there is no auto-discoverable connection (ex: the process was
   spawned without links or the logic is within a message handling callback).
 
   This connection will persist until the process exits or
-  `NewRelic.disconnect_from_transaction()` is called.
+  `NewRelic.disconnect_from_transaction/0` is called.
   """
   defdelegate connect_to_transaction(ref), to: NewRelic.Transaction.Reporter
 
@@ -166,9 +171,22 @@ defmodule NewRelic do
   Store information about the type of work the current span is doing.
 
   Options:
-  - `:generic, custom: attributes`
-  - `:http, url: url, method: method, component: component`
-  - `:datastore, statement: statement, instance: instance, address: address, hostname: hostname, component: component`
+  - `:type`
+    - `:generic` - Pass custom attributes
+    - `:http` - Pass attributes `:url`, `:method`, `:component`
+    - `:datastore` - Pass attrributes `:statement`, `:instance`, `:address`, `:hostname`,
+      `:component`
+
+  ## Examples
+
+  ```elixir
+  NewRelic.set_span(:generic, some: "attribute")
+
+  NewRelic.set_span(:http, url: "https://elixir-lang.org", method: "GET", component: "HTTPoison")
+
+  NewRelic.set_span(:datastore, statement: statement, instance: instance, address: address,
+  hostname: hostname, component: component)
+  ```
   """
   defdelegate set_span(type, attributes), to: NewRelic.DistributedTrace
 
@@ -182,14 +200,17 @@ defmodule NewRelic do
   HTTPoison.get(url, ["x-api-key": "secret"] ++ NewRelic.distributed_trace_headers(:http))
   ```
 
-  **Notes:**
+  ## Notes
 
-  * Call `NewRelic.distributed_trace_headers` immediately before making the
+  * Call `distributed_trace_headers` immediately before making the
   request since calling the function marks the "start" time of the request.
   """
   defdelegate distributed_trace_headers(type), to: NewRelic.DistributedTrace
 
-  @deprecated "Use distributed_trace_headers/1 instead"
+  @doc """
+  See: `NewRelic.distributed_trace_headers/1`
+  """
+  @deprecated "Use distributed_trace_headers instead"
   defdelegate create_distributed_trace_payload(type),
     to: NewRelic.DistributedTrace,
     as: :distributed_trace_headers
@@ -222,6 +243,8 @@ defmodule NewRelic do
   @doc """
   Report a Custom event to NRDB.
 
+  ## Example
+
   ```elixir
   NewRelic.report_custom_event("EventType", %{"foo" => "bar"})
   ```
@@ -233,6 +256,8 @@ defmodule NewRelic do
   Report a Dimensional Metric.
   Valid types: `:count`, `:gauge`, and `:summary`.
 
+  ## Example
+
   ```elixir
   NewRelic.report_dimensional_metric(:count, "my_metric_name", 1, %{some: "attributes"})
   ```
@@ -243,6 +268,8 @@ defmodule NewRelic do
   @doc """
   Report a Custom metric.
 
+  ## Example
+
   ```elixir
   NewRelic.report_custom_metric("My/Metric", 123)
   ```
@@ -253,6 +280,8 @@ defmodule NewRelic do
   @doc """
   Increment a Custom metric.
 
+  ## Example
+
   ```elixir
   NewRelic.increment_custom_metric("My/Metric")
   ```

lib/new_relic/tracer.ex

@@ -3,19 +3,21 @@ defmodule NewRelic.Tracer do
   Function Tracing
 
   To enable function tracing in a particular module, `use NewRelic.Tracer`,
-  and annotate the functions you want to `@trace`.
+  and annotate the functions you want to trace with `@trace`.
 
   Traced functions will report as:
   - Segments in Transaction Traces
   - Span Events in Distributed Traces
   - Special custom attributes on Transaction Events
 
-  #### Notes:
-
-  * Traced functions will *not* be tail-call-recursive. **Don't use this for recursive functions**.
+  > #### Warning {: .error}
+  >
+  > Traced functions will *not* be tail-call-recursive. **Don't use this for recursive functions**.
 
   #### Example
 
+  Trace as a function:
+
   ```elixir
   defmodule MyModule do
     use NewRelic.Tracer
@@ -31,7 +33,7 @@ defmodule NewRelic.Tracer do
 
   To categorize External Service calls you must give the trace annotation a category.
 
-  You may also call `NewRelic.set_span` to provide better naming for metrics & spans, and additonally annotate the outgoing HTTP headers with the Distributed Tracing context to track calls across services.
+  You may also call `NewRelic.set_span/2` to provide better naming for metrics & spans, and additonally annotate the outgoing HTTP headers with the Distributed Tracing context to track calls across services.
 
   ```elixir
   defmodule MyExternalService do

mix.lock

@@ -5,14 +5,14 @@
   "cowlib": {:hex, :cowlib, "2.12.1", "a9fa9a625f1d2025fe6b462cb865881329b5caff8f1854d1cbc9f9533f00e1e1", [:make, :rebar3], [], "hexpm", "163b73f6367a7341b33c794c4e88e7dbfe6498ac42dcd69ef44c5bc5507c8db0"},
   "db_connection": {:hex, :db_connection, "2.6.0", "77d835c472b5b67fc4f29556dee74bf511bbafecdcaf98c27d27fa5918152086", [:mix], [{:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "c2f992d15725e721ec7fbc1189d4ecdb8afef76648c746a8e1cad35e3b8a35f3"},
   "decimal": {:hex, :decimal, "2.1.1", "5611dca5d4b2c3dd497dec8f68751f1f1a54755e8ed2a966c2633cf885973ad6", [:mix], [], "hexpm", "53cfe5f497ed0e7771ae1a475575603d77425099ba5faef9394932b35020ffcc"},
-  "earmark_parser": {:hex, :earmark_parser, "1.4.39", "424642f8335b05bb9eb611aa1564c148a8ee35c9c8a8bba6e129d51a3e3c6769", [:mix], [], "hexpm", "06553a88d1f1846da9ef066b87b57c6f605552cfbe40d20bd8d59cc6bde41944"},
+  "earmark_parser": {:hex, :earmark_parser, "1.4.41", "ab34711c9dc6212dda44fcd20ecb87ac3f3fce6f0ca2f28d4a00e4154f8cd599", [:mix], [], "hexpm", "a81a04c7e34b6617c2792e291b5a2e57ab316365c2644ddc553bb9ed863ebefa"},
   "ecto": {:hex, :ecto, "3.11.1", "4b4972b717e7ca83d30121b12998f5fcdc62ba0ed4f20fd390f16f3270d85c3e", [:mix], [{:decimal, "~> 2.0", [hex: :decimal, repo: "hexpm", optional: false]}, {:jason, "~> 1.0", [hex: :jason, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "ebd3d3772cd0dfcd8d772659e41ed527c28b2a8bde4b00fe03e0463da0f1983b"},
   "ecto_sql": {:hex, :ecto_sql, "3.11.1", "e9abf28ae27ef3916b43545f9578b4750956ccea444853606472089e7d169470", [:mix], [{:db_connection, "~> 2.4.1 or ~> 2.5", [hex: :db_connection, repo: "hexpm", optional: false]}, {:ecto, "~> 3.11.0", [hex: :ecto, repo: "hexpm", optional: false]}, {:myxql, "~> 0.6.0", [hex: :myxql, repo: "hexpm", optional: true]}, {:postgrex, "~> 0.16.0 or ~> 0.17.0 or ~> 1.0", [hex: :postgrex, repo: "hexpm", optional: true]}, {:tds, "~> 2.1.1 or ~> 2.2", [hex: :tds, repo: "hexpm", optional: true]}, {:telemetry, "~> 0.4.0 or ~> 1.0", [hex: :telemetry, repo: "hexpm", optional: false]}], "hexpm", "ce14063ab3514424276e7e360108ad6c2308f6d88164a076aac8a387e1fea634"},
-  "ex_doc": {:hex, :ex_doc, "0.31.0", "06eb1dfd787445d9cab9a45088405593dd3bb7fe99e097eaa71f37ba80c7a676", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.1", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1", [hex: :makeup_erlang, repo: "hexpm", optional: false]}], "hexpm", "5350cafa6b7f77bdd107aa2199fe277acf29d739aba5aee7e865fc680c62a110"},
+  "ex_doc": {:hex, :ex_doc, "0.35.1", "de804c590d3df2d9d5b8aec77d758b00c814b356119b3d4455e4b8a8687aecaf", [:mix], [{:earmark_parser, "~> 1.4.39", [hex: :earmark_parser, repo: "hexpm", optional: false]}, {:makeup_c, ">= 0.1.0", [hex: :makeup_c, repo: "hexpm", optional: true]}, {:makeup_elixir, "~> 0.14 or ~> 1.0", [hex: :makeup_elixir, repo: "hexpm", optional: false]}, {:makeup_erlang, "~> 0.1 or ~> 1.0", [hex: :makeup_erlang, repo: "hexpm", optional: false]}, {:makeup_html, ">= 0.1.0", [hex: :makeup_html, repo: "hexpm", optional: true]}], "hexpm", "2121c6402c8d44b05622677b761371a759143b958c6c19f6558ff64d0aed40df"},
   "jason": {:hex, :jason, "1.4.1", "af1504e35f629ddcdd6addb3513c3853991f694921b1b9368b0bd32beb9f1b63", [:mix], [{:decimal, "~> 1.0 or ~> 2.0", [hex: :decimal, repo: "hexpm", optional: true]}], "hexpm", "fbb01ecdfd565b56261302f7e1fcc27c4fb8f32d56eab74db621fc154604a7a1"},
-  "makeup": {:hex, :makeup, "1.1.1", "fa0bc768698053b2b3869fa8a62616501ff9d11a562f3ce39580d60860c3a55e", [:mix], [{:nimble_parsec, "~> 1.2.2 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "5dc62fbdd0de44de194898b6710692490be74baa02d9d108bc29f007783b0b48"},
-  "makeup_elixir": {:hex, :makeup_elixir, "0.16.1", "cc9e3ca312f1cfeccc572b37a09980287e243648108384b97ff2b76e505c3555", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "e127a341ad1b209bd80f7bd1620a15693a9908ed780c3b763bccf7d200c767c6"},
-  "makeup_erlang": {:hex, :makeup_erlang, "0.1.3", "d684f4bac8690e70b06eb52dad65d26de2eefa44cd19d64a8095e1417df7c8fd", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "b78dc853d2e670ff6390b605d807263bf606da3c82be37f9d7f68635bd886fc9"},
+  "makeup": {:hex, :makeup, "1.2.1", "e90ac1c65589ef354378def3ba19d401e739ee7ee06fb47f94c687016e3713d1", [:mix], [{:nimble_parsec, "~> 1.4", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "d36484867b0bae0fea568d10131197a4c2e47056a6fbe84922bf6ba71c8d17ce"},
+  "makeup_elixir": {:hex, :makeup_elixir, "1.0.1", "e928a4f984e795e41e3abd27bfc09f51db16ab8ba1aebdba2b3a575437efafc2", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}, {:nimble_parsec, "~> 1.2.3 or ~> 1.3", [hex: :nimble_parsec, repo: "hexpm", optional: false]}], "hexpm", "7284900d412a3e5cfd97fdaed4f5ed389b8f2b4cb49efc0eb3bd10e2febf9507"},
+  "makeup_erlang": {:hex, :makeup_erlang, "1.0.1", "c7f58c120b2b5aa5fd80d540a89fdf866ed42f1f3994e4fe189abebeab610839", [:mix], [{:makeup, "~> 1.0", [hex: :makeup, repo: "hexpm", optional: false]}], "hexpm", "8a89a1eeccc2d798d6ea15496a6e4870b75e014d1af514b1b71fa33134f57814"},
   "mime": {:hex, :mime, "2.0.5", "dc34c8efd439abe6ae0343edbb8556f4d63f178594894720607772a041b04b02", [:mix], [], "hexpm", "da0d64a365c45bc9935cc5c8a7fc5e49a0e0f9932a761c55d6c52b142780a05c"},
   "nimble_options": {:hex, :nimble_options, "1.1.0", "3b31a57ede9cb1502071fade751ab0c7b8dbe75a9a4c2b5bbb0943a690b63172", [:mix], [], "hexpm", "8bbbb3941af3ca9acc7835f5655ea062111c9c27bcac53e004460dfd19008a99"},
   "nimble_parsec": {:hex, :nimble_parsec, "1.4.0", "51f9b613ea62cfa97b25ccc2c1b4216e81df970acd8e16e8d1bdc58fef21370d", [:mix], [], "hexpm", "9c565862810fb383e9838c1dd2d7d2c437b3d13b267414ba6af33e50d2d1cf28"},