Allow recording links only at Span creation time

specification/api-tracing.md

@@ -20,12 +20,12 @@ Table of Contents
 * [SpanContext](#spancontext)
 * [Span](#span)
   * [Span creation](#span-creation)
+    * [Add Links](#add-links)
   * [Span operations](#span-operations)
     * [Get Context](#get-context)
     * [IsRecordingEvents](#isrecordingevents)
     * [Set Attributes](#set-attributes)
     * [Add Events](#add-events)
-    * [Add Links](#add-links)
     * [Set Status](#set-status)
     * [UpdateName](#updatename)
     * [End](#end)
@@ -183,14 +183,14 @@ sub-operations.
 `Span`s encapsulate:
 
 - The operation name
-- An immutable [`SpanContext`](#SpanContext) that uniquely identifies the
+- An immutable [`SpanContext`](#spancontext) that uniquely identifies the
   `Span`
-- A parent span in the form of a [`Span`](#Span), [`SpanContext`](#SpanContext),
+- A parent span in the form of a [`Span`](#span), [`SpanContext`](#spancontext),
   or null
 - A start timestamp
 - An end timestamp
-- An ordered mapping of [`Attribute`s](#Set-Attributes)
-- A list of [`Link`s](#add-Links) to other `Span`s
+- An ordered mapping of [`Attribute`s](#set-attributes)
+- A list of [`Link`s](#span-creation) to other `Span`s
 - A list of timestamped [`Event`s](#add-events)
 - A [`Status`](#set-status).
 
@@ -220,8 +220,8 @@ The API SHOULD require the caller to provide:
 
 The API MUST allow users to provide the following properties, which SHOULD be
 empty by default:
-- `Attribute`s
-- `Link`s
+- `Attribute`s - similar API with [Span::SetAttributes](#set-attributes)
+- `Link`s - see API definition [here](#links)
 - `Event`s
 - `Start timestamp`
 
@@ -237,6 +237,28 @@ created in another process. Since the `SpanContext` is the only component of a
 `Span` that is propagated between processes, a `Span`'s parent SHOULD be a
 `SpanContext` if it is remote. Otherwise, it may be a `Span` or `SpanContext`.
 
+#### Add Links
+
+During the `Span` creation user MUST have the ability to record links to other `Span`s. Linked
+`Span`s can be from the same or a different trace. See [Links
+description](overview.md#links-between-spans).
+
+A `Link` is defined by the following properties:
+- (Required) `SpanContext` of the `Span` to link to.
+- (Optional) One or more `Attribute`.
+
+The `Link` SHOULD be an immutable type.
+
+The Span creation API should provide:
+- An API to record a single `Link` where the `Link` properties are passed as
+arguments. This MAY be called `AddLink`.
+- An API to record a single lazily initialized `Link`. This can be implemented
+by providing a `Link` interface or a concrete `Link` definition and a
+`LinkFormatter`. If the language supports overloads then this MAY be called
+`AddLink` otherwise `AddLazyLink` MAY be consider.
+
+Links SHOULD preserve the order in which they're set.
+
 ### Span operations
 
 With the exception of the method to retrieve the `Span`'s `SpanContext` and
@@ -305,28 +327,6 @@ the ordering of the events' timestamps.
 Note that the OpenTelemetry project documents certain ["standard event names and
 keys"](data-semantic-conventions.md) which have prescribed semantic meanings.
 
-#### Add Links
-
-A `Span` MUST have the ability to record links to other `Span`s. Linked `Span`s
-can be from the same or a different trace. See [Links
-description](overview.md#links-between-spans).
-
-A `Link` is defined by the following properties:
-- (Required) `SpanContext` of the `Span` to link to.
-- (Optional) One or more `Attribute`.
-
-The `Link` SHOULD be an immutable type.
-
-The Span interface MUST provide:
-- An API to record a single `Link` where the `Link` properties are passed as
-arguments. This MAY be called `AddLink`.
-- An API to record a single lazily initialized `Link`. This can be implemented
-by providing a `Link` interface or a concrete `Link` definition and a
-`LinkFormatter`. If the language supports overloads then this MAY be called
-`AddLink` otherwise `AddLazyLink` MAY be consider.
-
-Links SHOULD preserve the order in which they're set.
-
 #### Set Status
 
 Sets the [`Status`](#status) of the `Span`. If used, this will override the