Minor changes to comments (#1390)

* Minor changes to comments

* remove tracestateutils

src/OpenTelemetry.Api/Context/Propagation/IPropagator.cs

@@ -20,8 +20,8 @@ using System.Collections.Generic;
 namespace OpenTelemetry.Context.Propagation
 {
     /// <summary>
-    /// Text format wire context propagator. Helps to extract and inject context from textual
-    /// representation (typically http headers or metadata collection).
+    /// Defines an interface for Propagator, which is used to read and write
+    /// context data from and to message exchanges by the applications.
     /// </summary>
     public interface IPropagator
     {
@@ -33,7 +33,7 @@ namespace OpenTelemetry.Context.Propagation
         ISet<string> Fields { get; }
 
         /// <summary>
-        /// Injects textual representation of activity context to transmit over the wire.
+        /// Injects the context into a carrier.
         /// </summary>
         /// <typeparam name="T">Type of an object to set context on. Typically HttpRequest or similar.</typeparam>
         /// <param name="context">The default context to transmit over the wire.</param>
@@ -42,7 +42,7 @@ namespace OpenTelemetry.Context.Propagation
         void Inject<T>(PropagationContext context, T carrier, Action<T, string, string> setter);
 
         /// <summary>
-        /// Extracts activity context from textual representation.
+        /// Extracts the context from a carrier.
         /// </summary>
         /// <typeparam name="T">Type of object to extract context from. Typically HttpRequest or similar.</typeparam>
         /// <param name="context">The default context to be used if Extract fails.</param>

src/OpenTelemetry.Api/Context/Propagation/TraceStateUtilsNew.cs

@@ -21,11 +21,7 @@ using System.Linq;
 using System.Text;
 using OpenTelemetry.Internal;
 
-#if API
-namespace OpenTelemetry.Api.Context.Propagation
-#else
 namespace OpenTelemetry.Context.Propagation
-#endif
 {
     /// <summary>
     /// Extension methods to extract TraceState from string.

src/OpenTelemetry.Api/Internal/OpenTelemetryApiEventSource.cs

@@ -21,6 +21,7 @@ namespace OpenTelemetry.Internal
 {
     /// <summary>
     /// EventSource implementation for OpenTelemetry API.
+    /// This is used for internal logging of this library.
     /// </summary>
     [EventSource(Name = "OpenTelemetry-Api")]
     internal class OpenTelemetryApiEventSource : EventSource

src/OpenTelemetry.Api/Trace/SpanAttributes.cs

@@ -23,6 +23,7 @@ namespace OpenTelemetry.Trace
     /// <summary>
     /// A class that represents the span attributes. Read more here https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/common/common.md#attributes.
     /// </summary>
+    /// <remarks>SpanAttributes is a wrapper around <see cref="ActivityTagsCollection"/> class.</remarks>
     public class SpanAttributes
     {
         /// <summary>

src/OpenTelemetry.Api/Trace/SpanContext.cs

@@ -16,15 +16,18 @@
 using System.Collections.Generic;
 using System.Diagnostics;
 using System.Linq;
-using OpenTelemetry.Api.Context.Propagation;
+using OpenTelemetry.Context.Propagation;
 
 namespace OpenTelemetry.Trace
 {
     /// <summary>
-    /// A class that represents a span context. A span context contains the state that must propagate to
-    /// child <see cref="TelemetrySpan"/> and across process boundaries. It contains the identifiers <see cref="ActivityTraceId"/>
-    /// and <see cref="ActivitySpanId"/> associated with the <see cref="TelemetrySpan"/> and a set of <see cref="TraceFlags"/>.
+    /// A class that represents a span context. A span context contains the portion of a span
+    /// that must propagate to child <see cref="TelemetrySpan"/> and across process boundaries.
+    /// It contains the identifiers <see cref="ActivityTraceId"/>and <see cref="ActivitySpanId"/>
+    /// associated with the <see cref="TelemetrySpan"/> along with a set of
+    /// common <see cref="TraceFlags"/> and system-specific <see cref="TraceState"/> values>.
     /// </summary>
+    /// <remarks>SpanContext is a wrapper around <see cref="ActivityContext"/>.</remarks>
     public readonly struct SpanContext : System.IEquatable<SpanContext>
     {
         internal readonly ActivityContext ActivityContext;

src/OpenTelemetry.Api/Trace/TelemetrySpan.cs

@@ -22,10 +22,9 @@ using OpenTelemetry.Internal;
 namespace OpenTelemetry.Trace
 {
     /// <summary>
-    /// <para>Span represents the execution of the certain span of code or span of time between two events which is part of
-    /// a distributed trace and has result of execution, context of execution and other properties.</para>
+    /// Span represents a single operation within a trace.
     /// </summary>
-    /// <remarks>Represents OpenTelemetry Span https://github.com/open-telemetry/opentelemetry-specification/blob/master/specification/trace/api.md#span.</remarks>
+    /// <remarks>TelemetrySpan is a wrapper around <see cref="Activity"/> class.</remarks>
     public class TelemetrySpan : IDisposable
     {
         internal static readonly TelemetrySpan NoopInstance = new TelemetrySpan(null);

src/OpenTelemetry.Api/Trace/Tracer.cs

@@ -23,8 +23,9 @@ using System.Runtime.CompilerServices;
 namespace OpenTelemetry.Trace
 {
     /// <summary>
-    /// Tracer to record distributed tracing information.
+    /// Tracer is the class responsible for creating <see cref="TelemetrySpan"/>.
     /// </summary>
+    /// <remarks>Tracer is a wrapper around <see cref="ActivitySource"/> class.</remarks>
     public class Tracer
     {
         internal readonly ActivitySource ActivitySource;

src/OpenTelemetry.Api/Trace/TracerProvider.cs

@@ -20,7 +20,7 @@ using System.Diagnostics;
 namespace OpenTelemetry.Trace
 {
     /// <summary>
-    /// TracerProvider is the entry point of the OpenTelemetry API. It provides access to Tracers.
+    /// TracerProvider is the entry point of the OpenTelemetry API. It provides access to <see cref="Tracer"/>.
     /// </summary>
     public class TracerProvider : IDisposable
     {

src/OpenTelemetry/OpenTelemetry.csproj

@@ -9,7 +9,6 @@
   </PropertyGroup>
 
   <ItemGroup>
-    <Compile Include="$(RepoRoot)\src\OpenTelemetry.Api\Context\Propagation\TraceStateUtilsNew.cs" Link="Utils\TraceStateUtilsNew.cs" />
     <Compile Include="$(RepoRoot)\src\OpenTelemetry.Api\Internal\ExceptionExtensions.cs" Link="Internal\ExceptionExtensions.cs" />
   </ItemGroup>