Merge pull request #16075 from pharring/typos

Fix typos in DiagnosticSource

3 files changed, 106 insertions, 98 deletions

diff --git a/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md b/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md
index e768ccaf77..06b838ad70 100644
--- a/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md
+++ b/src/System.Diagnostics.DiagnosticSource/src/ActivityUserGuide.md
@@ -5,69 +5,69 @@ This document describes Activity, a class that allows storing and accessing diag
 This document provides Activity architecture [overview](#overview) and [usage](#activity-usage).
 
 # Overview
-When application starts procesing an operation e.g. HTTP request or task from queue, it creates an `Activity` to track it through the system as the request is processed. Examples of context stored in `Activity` could be HTTP request path, method, user-agent, or correlation id: all the details important to be logged along with every trace. 
+When application starts processing an operation e.g. HTTP request or task from queue, it creates an `Activity` to track it through the system as the request is processed. Examples of context stored in `Activity` could be HTTP request path, method, user-agent, or correlation id: all the details important to be logged along with every trace. 
 When application calls external dependency to complete an operation, it may need to pass some of the context (e.g. correlation id) along with dependency call to be able to correlate logs from multiple services.
 
 `Activity` provides [Tags](#tags) to represent context which is needed for logging only and [Baggage](#baggage) to represent context which needs to be propagated to external dependencies. It has other properties described in [Activity Reference](#activity-reference).
 
-Every `Activity` has an `Id`, defining particular request in application, which is generated when Actvitity is started.
+Every `Activity` has an `Id`, defining particular request in application, which is generated when Activity is started.
 
 `Activity` (except root one) has a [Parent](#parent) (in-process or external). E.g. application calls external dependency while processing incoming request, so there is an Activity for dependency call and it has Parent Activity representing incoming call.
-External dependency Activity Id is passed along with the request, so the dependency may use it as ParentId for it's activities and thus allow unique mapping between child and parent calls. Parent is assigned when activity is started.
+External dependency Activity Id is passed along with the request, so the dependency may use it as ParentId for its activities and thus allow unique mapping between child and parent calls. Parent is assigned when activity is started.
 
 Activities may be created and started/stopped by platform code or frameworks; applications need to be notified about activities events and need to have access to current activity being processed.
 Therefore code which creates activity also writes corresponding event to `DiagnosticSource`:
-- DO - create new `DiagnosticListener` for specific Activity type to allow filtering by activity. E.g Incoming and Outgoing Http Requests should be different DiagnosticListeners. Follow [DiagnosticSource User Guilde](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md) to peek a name.
-- DO - Guard Activity creation and start with call to `DiagnosticSource.IsEnabled` to avoid creating activities if no one listens to them and enable event name-based filtering or sampling.
-- DO - Use `DiagnosticSource.StartActivity(Actvity)` and `DiagnosticSource.StopActivity(Actvity)` methods instead of Activity methods to ensure Activity events are always written to `DiagnosticSource`.
-- DO - pass necessary context to `DiagnosticListener`, so application may enrich Activity. In case of HTTP incoming request, application needs `HttpContext` to add custom tags (method, path, user-agent, etc)
-- CONSIDER - keeping baggage as small as possible
-- DO NOT - add sensitive information to baggage, since it may be propagated out of the process boundaries
-- DO - write activity [Id](#id) with every telemetry event, ParentId, Tags and Baggage should be written at least once per operation and could be found by Id. Note that tags and baggage could be changed through the lifetime of activity, and it makes sense to write them when activity stops. Duration should only be logged when activity stops.
+- DO - create new `DiagnosticListener` for specific Activity type to allow filtering by activity. E.g Incoming and Outgoing Http Requests should be different DiagnosticListeners. Follow [DiagnosticSource User Guide](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md) to pick a name.
+- DO - Guard Activity creation and start with call to `DiagnosticSource.IsEnabled` to avoid creating activities when no-one is listening to them and to enable event name-based filtering or sampling.
+- DO - Use `DiagnosticSource.StartActivity(Activity)` and `DiagnosticSource.StopActivity(Activity)` methods instead of Activity methods to ensure Activity events are always written to `DiagnosticSource`.
+- DO - pass any necessary context to `DiagnosticListener`, so your application may enrich Activity. For example, in the case of an incoming HTTP request, the application needs an instance of `HttpContext` in order to add custom tags (method, path, user-agent, etc.)
+- CONSIDER - keeping [Baggage](#baggage) as small as possible.
+- DO NOT - add sensitive information to baggage, since it may be propagated out of the process boundaries.
+- DO - write activity [Id](#id) with every telemetry event. [ParentId](#parentid), [Tags](#tags) and [Baggage](#baggage) should be written at least once per operation and could be found by Id. Note that Tags and Baggage could be changed through the lifetime of activity, and it makes sense to write them when the activity stops. [Duration](#duration) should be logged only when the activity stops.
 
-Current Activity is exposed as statis variable and flows with async calls so in every Start/Stop event callback it is accurate and may be used to log these events.
+The current activity is exposed as static variable, `Activity.Current`, and flows with call context, including async calls, so that it is available in every Start/Stop event callback.
 
 Applications may access `Activity.Current` anywhere in the code to log events along with the context stored in Activity.
 # Activity Usage
-At the moment application writes log record, it can access `Activity.Current` to get all required details from it.
+At the moment an application writes log record, it can access `Activity.Current` to get all required details from it.
 
 ## Creating Activities
 ```C#
     Activity activity = new Activity("Http_In");
 ```
-Activity can be created with operation name. This is an coarse name that is useful for grouping and filtering log records.
+An activity must be created with an operation name. This is a coarse name that is useful for grouping and filtering log records.
 
-After Activity is created you can add additional details: [Start time](#starttimeutc), [Tags](#tags) and [Baggage](#baggage)
+After an Activity is created you can add additional details: [Start time](#starttimeutc), [Tags](#tags) and [Baggage](#baggage)
 ```C#
    activity.SetStartTime(GetHighPrecisionTimestamp())
            .AddTag("Path", request.Path)
            .AddBaggage("CorrelationId", request.Headers["x-ms-correlation-id"]);
 ```
-When activity is built, it's time to start it and continue with request processing.
+Once an activity has been built, it's time to start it and continue with request processing.
 
-## Starting and Stoping Activity
+## Starting and Stopping Activity
 
-Activity.Start() and Stop() methods maitain [Activity.Current](current) which flows with async calls and available during request processing.
-When activity is started, it assigned with an [Id](id) and [Parent](parent).
+The `Start()` and `Stop()` methods maintain [Activity.Current](current) which flows with async calls and is available during request processing.
+When that activity is started, it is given an [Id](id) and a [Parent](parent).
 
 ```C#
    public void OnIncomingRequest(DiagnosticListener httpListener, HttpContext request)
    {
        if (httpListener.IsEnabled("Http_In"))
        {
-           Activity activity = new Activity("Http_In");           
-		   activity.SetStartTime(GetHighPrecisionTimestamp())
-           //add tags, baggage, etc..           
+           Activity activity = new Activity("Http_In");
+           activity.SetStartTime(GetHighPrecisionTimestamp())
+           //add tags, baggage, etc.
            activity.SetParentId(context.Request.headers["x-ms-request-id"])
            foreach (var header in context.Request.Headers)
              if (header.Key.StartsWith("x-baggage-")
                  activity.AddBaggage(header.Key, header.Value);
                  
-           httpListener.StartActivity(activity, httpContext);               
+           httpListener.StartActivity(activity, httpContext);
            try {
                //process request ...
            } finally {
-		   	   activity.SetEndTime(GetHighPrecisionTimestamp());
+               activity.SetEndTime(GetHighPrecisionTimestamp());
                //stop activity
                httpListener.StopActivity(activity, highPrecisionStopTime);
            }       
@@ -76,12 +76,12 @@ When activity is started, it assigned with an [Id](id) and [Parent](parent).
 ```
 **Note** 
 - instead of Activity.Start() and Stop() methods, in above example we call `DiagnosticSource.StartActivity()` and `StopActivity()` methods that write events to DiagnosticSource.
-- Activities creation is guarded with `DiagnosticSource.IsEnabled` and will only happen if someone listens to this `DiagnosticSource` thus eliminating any unnecessary performance impact.
-- DateTime.UtcNow in practice is [precise to 16 milliseconds](https://blogs.msdn.microsoft.com/ericlippert/2010/04/08/precision-and-accuracy-of-datetime/). If you are interested in better preceision, call [SetStartTime](#setstarttime) and [SetEndTime](#setendtime) with high precesion timestamp, which you may achieve with combination of DateTime and Stopwatch
+- Activity creation is guarded with a call to `DiagnosticSource.IsEnabled` thus eliminating any unnecessary performance impact if no-one is listening to this `DiagnosticSource`.
+- DateTime.UtcNow in practice is [accurate to 16 milliseconds](https://blogs.msdn.microsoft.com/ericlippert/2010/04/08/precision-and-accuracy-of-datetime/). If you want better accuracy, call [SetStartTime](#setstarttime) and [SetEndTime](#setendtime) with a timestamp derived from a combination of `DateTime` and `System.Diagnostics.Stopwatch`.
 
 
 ## Creating child Activities
-When application calls external web-service, new activity is created to represent external operation. This activity may have Parent (if this request is part of incoming request processing), assigned to it during Start().
+When an application makes an outbound call, for example to an external web-service, a new activity should be created. If this child activity is part of an existing activity then its Parent will be assigned automatically during Start().
 
 ```C#
     public void OnOutgoingRequest(DiagnosticListener httpListener, HttpRequestMessage request)
@@ -97,7 +97,7 @@ When application calls external web-service, new activity is created to represen
             try {
                //process request ...
             } finally {
-		   	    activity.SetEndTime(GetHighPrecisionTimestamp());
+                activity.SetEndTime(GetHighPrecisionTimestamp());
                 //stop activity
                 httpListener.StopActivity(activity, value.Value, DateTimeStopwatch.GetTime(timestamp));
             }       
@@ -105,17 +105,17 @@ When application calls external web-service, new activity is created to represen
     }
 ```
 
-New Activity will inherit Baggage from parent. Above example demonstrates how baggage could be propagated to downstream web-service in HTTP request headers.
+The child Activity will automatically inherit Baggage from its parent. The above example also demonstrates how baggage could be propagated to a downstream web service in HTTP request headers.
 
-Similarly to incoming request processing, activity creation should be guarded with `DiagnosticSource.IsEnabled()` call, however allowing to filter headers injection based on request Uri.
-Note that different DiagnosticSources should be used for incoming and outgoing HTTP activities allowing to implement separate filtering for events.
+Just as in the previous example, activity creation should be guarded with a `DiagnosticSource.IsEnabled()` call. In this case, however, it prevents headers injection based on request Uri.
+Note that different DiagnosticSources should be used for incoming and outgoing HTTP activities allowing you to implement separate filtering for events.
 
 ## Listening to Activity Events
-Application may listen to activity events and log them. It can access `Activity.Current` to get information about current activity.
-This follows normal [DiagnosticListener conventions](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md)
+An application may listen to activity events and log them. It can access `Activity.Current` to get information about the current activity.
+This follows normal [DiagnosticListener conventions](https://github.com/dotnet/corefx/blob/master/src/System.Diagnostics.DiagnosticSource/src/DiagnosticSourceUsersGuide.md).
 
-Application may also add tags and baggage to current activity when processing Activity start callback.
-Note in the [Incoming Request Sample](#starting-and-stoping-activity), we pass `HttpContext` to DiagnosticSource, so application may access request properties to enrich current activity.
+An application may also add tags and baggage to the current activity when processing an Activity start callback.
+Note that in the [Incoming Request Sample](#starting-and-stopping-activity), we pass `HttpContext` to DiagnosticSource, so that the application has access to the request properties in order to enrich the current activity.
 
 ### Subscribe to DiagnosticSource
 ```
@@ -125,13 +125,13 @@ Note in the [Incoming Request Sample](#starting-and-stoping-activity), we pass `
         {
             listener.Subscribe(delegate (KeyValuePair<string, object> value)
             {
-                if (value.Key.EndsWith("Start"))
+                if (value.Key.EndsWith("Start", StringComparison.Ordinal))
                     LogActivityStart();
-                else if (value.Key.EndsWith("Stop"))
+                else if (value.Key.EndsWith("Stop", StringComparison.Ordinal))
                     LogActivityStop();
             });
         }
-	}
+    }
 ```
 
 ### Log Events
@@ -190,62 +190,62 @@ It's crucial that Activity Id is logged along with every event. ParentId, Tags a
 # Reference
 ## Activity
 ### Tags
-`IEnumerable<KeyValuePair<string, string>> Tags { get; }` - Represents information to be logged along with activity. Good examples of tags are instance/machine name, incoming request HTTP method, path, user/user-agent, etc. Tags are **not passed** to the children of Activity.
-Typical tag usage includes adding a few custom tags and enumeration through them to fill log event payload. Getting tag by it's key is not supported.
+`IEnumerable<KeyValuePair<string, string>> Tags { get; }` - Represents information to be logged along with the activity. Good examples of tags are instance/machine name, incoming request HTTP method, path, user/user-agent, etc. Tags are **not passed** to child of activities.
+Typical tag usage includes adding a few custom tags and enumeration through them to fill log event payload. Retrieving a tag by its key is not supported.
 
 ### Baggage
-`IEnumerable<KeyValuePair<string, string>> Baggage { get; }` - Represents information to be logged woth activity AND passed to it's children. Examples of baggage include correlation id, sampling and feature flags.
-Baggage is serialized and **passed it along with external dependency request**.
+`IEnumerable<KeyValuePair<string, string>> Baggage { get; }` - Represents information to be logged with the activity **and** passed to its children. Examples of baggage include correlation id, sampling and feature flags.
+Baggage is serialized and **passed along with external dependency requests**.
 Typical Baggage usage includes adding a few baggage properties and enumeration through them to fill log event payload. 
 
 ### OperationName
-`string OperationName { get; }` - Coarset name for an activity
+`string OperationName { get; }` - Coarsest name for an activity. This name must be set in the constructor.
  
 ### StartTimeUtc
-`DateTime StartTimeUtc { get; private set; }`  - DateTime in UTC (Greenwitch Mean Time) when activity was started. DateTime.UtcNow if not specified
+`DateTime StartTimeUtc { get; private set; }`  - DateTime in UTC (Greenwich Mean Time) when activity was started. If it's not already initialized, it will be set to DateTime.UtcNow in `Start`.
 
 ### Duration 
-`TimeSpan Duration { get; private set; }` - Represent Activity duration if activity was stopped, TimeSpan.Zero otherwise
+`TimeSpan Duration { get; private set; }` - Represents Activity duration if activity was stopped, TimeSpan.Zero otherwise.
 
 ### Id
-`string Id { get; private set; }` - Represents particular activity identifier. Filtering to a particular Id insures that you get only log records related to specific request within the operation. It is assigned when activity is started.
+`string Id { get; private set; }` - Represents particular activity identifier. Filtering to a particular Id insures that you get only log records related to specific request within the operation. It is generated when the activity is started.
 Id is passed to external dependencies and considered as [ParentId](#parentid) for new external activity.
 
 ### ParentId
-`string ParentId { get; private set; }` - Activity may have either in-process [Parent](#parent) or Id of external Parent if it was deserialized from request. ParentId together with Id represent parent-child relationship in logs and allows to uniquely map outgoing and incoming requests.
+`string ParentId { get; private set; }` - Activity may have either an in-process [Parent](#parent) or an external Parent if it was deserialized from request. ParentId together with Id represent the parent-child relationship in logs and allows you to correlate outgoing and incoming requests.
 
 ### Current
-`static Activity Current { get; }` - Returns current Activity which flows across async calls
+`static Activity Current { get; }` - Returns current Activity which flows across async calls.
 
 ### Parent
 `Activity Parent { get; private set; }` - If activity was created from another activity in the same process, you can get that Activity with the Parent accessor. However this can be null if the Activity is root activity or parent is from outside the process.
 
 ### Start()
-`Activity Start()` - Starts Activity: sets Activity.Current and Parent for the activity.
+`Activity Start()` - Starts Activity: sets Activity.Current and Parent for the activity, generates a unique Id and sets the StartTimeUtc if not already set.
 
 ### Stop()
 `void Stop()` - Stops Activity: sets Activity.Current and Duration for the activity. Uses timestamp provided in [SetEndTime](#setendtime) or DateTime.UtcNow.
 
 ### AddBaggage()
-`Activity AddBaggage(string key, string value)` - adds baggage item, see [Baggage](#baggage)
+`Activity AddBaggage(string key, string value)` - adds a baggage item. See [Baggage](#baggage).
 
 ### GetBaggageItem()
-`string GetBaggageItem(string key)` - returns value of [Baggage](#baggage) key-value pair with given key, null if key does not exist
+`string GetBaggageItem(string key)` - returns the value of [Baggage](#baggage) key-value pair with given key or null if the key does not exist.
 
 ### AddTag()
-`Activity AddTag(string key, string value)` - adds tag, see [Tags](#tags)
+`Activity AddTag(string key, string value)` - adds a tag. See [Tags](#tags).
 
 ### SetParentId()
-`Activity SetParentId(string key, string value)` - sets parent Id, see [ParentId](#parentid)
+`Activity SetParentId(string parentId)` - sets the parent Id. See [ParentId](#parentid).
 
 ### SetStartTime
-`Activity SetStartTime(DateTime startTimeUtc)` - sets start time, see [StartTimeUtc](#starttimeutc)
+`Activity SetStartTime(DateTime startTimeUtc)` - sets the start time. See [StartTimeUtc](#starttimeutc).
 
 ### SetEndTime
-`Activity SetEndTime(DateTime endTimeUtc)` - sets [Duration](#duration) as a difference between endTimeUtc and [StartTimeUtc](#starttimeutc)
+`Activity SetEndTime(DateTime endTimeUtc)` - sets [Duration](#duration) as a difference between endTimeUtc and [StartTimeUtc](#starttimeutc).
 
 ##DiagnosticSource
 ### StartActivity
-`static Activity StartActivity(Activity activity, object args)` - Starts activity and writes DiagnosticSource event message OperationName.Start with args payload
+`Activity StartActivity(Activity activity, object args)` - Starts the given activity and writes DiagnosticSource event message OperationName.Start with args payload.
 ### StopActivity
-`static Activity StopActivity(Activity activity, object args)` - Stops activity and writes DiagnosticSource event OperationName.Stop with args payload
+`void StopActivity(Activity activity, object args)` - Stops the given activity and writes DiagnosticSource event OperationName.Stop with args payload.
diff --git a/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Activity.cs b/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Activity.cs
index cee254eb4b..80cf6a9706 100644
--- a/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Activity.cs
+++ b/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/Activity.cs
@@ -13,8 +13,8 @@ namespace System.Diagnostics
     ///  
     /// Current activity can be accessed with static AsyncLocal variable Activity.Current.
     /// 
-    /// Activities should be created with constructor, configured as necessarily 
-    /// and then started with Activity.Start method which maintaines parent-child
+    /// Activities should be created with constructor, configured as necessary
+    /// and then started with Activity.Start method which maintains parent-child
     /// relationships for the activities and sets Activity.Current.
     /// 
     /// When activity is finished, it should be stopped with static Activity.Stop method.
@@ -23,7 +23,7 @@ namespace System.Diagnostics
     {
         /// <summary>
         /// An operation name is a COARSEST name that is useful grouping/filtering. 
-        /// The name is typically a compile time constant.   Names of Rest APIs are 
+        /// The name is typically a compile-time constant.   Names of Rest APIs are
         /// reasonable, but arguments (e.g. specific accounts etc), should not be in
         /// the name but rather in the tags.  
         /// </summary>
@@ -31,27 +31,28 @@ namespace System.Diagnostics
 
         /// <summary>
         /// This is an ID that is specific to a particular request.   Filtering
-        /// to a particular ID insures that you get only one request that matches.  
-        /// It is typically assigned the system itself. 
+        /// to a particular ID ensures that you get only one request that matches.  
+        /// It is generated when <see cref="Start"/> is called.
         /// </summary>
         public string Id { get; private set; }
 
         /// <summary>
-        /// The time that operation started.  Typcially when Start() is called 
-        /// (but you can pass a value to Start() if necessary.  This use UTC (Greenwitch Mean Time)
+        /// The time that operation started.  It will typically be initialized when <see cref="Start"/>
+        /// is called, but you can set at any time via <see cref="SetStartTime(DateTime)"/>.
         /// </summary>
         public DateTime StartTimeUtc { get; private set; }
 
         /// <summary>
         /// If the Activity that created this activity is  from the same process you can get 
-        /// that Activit with Parent.   However this can be null if the Activity has no
-        /// parent (a root activity) or if the Parent is from outside the process.  (see ParentId for more)
+        /// that Activity with Parent.  However, this can be null if the Activity has no
+        /// parent (a root activity) or if the Parent is from outside the process.
         /// </summary>
+        /// <seealso cref="ParentId"/>
         public Activity Parent { get; private set; }
 
         /// <summary>
         /// If the parent for this activity comes from outside the process, the activity
-        /// does not have a Parent Activity but MAY have a ParentId (which was serialized from
+        /// does not have a Parent Activity but MAY have a ParentId (which was deserialized from
         /// from the parent) .   This accessor fetches the parent ID if it exists at all.  
         /// Note this can be null if this is a root Activity (it has no parent)
         /// </summary>
@@ -60,8 +61,9 @@ namespace System.Diagnostics
         /// <summary>
         /// Tags are string-string key-value pairs that represent information that will
         /// be logged along with the Activity to the logging system.   This information
-        /// however is NOT passed on to the children of this activity.  (see Baggage)
+        /// however is NOT passed on to the children of this activity.
         /// </summary>
+        /// <seealso cref="Baggage"/>
         public IEnumerable<KeyValuePair<string, string>> Tags
         {
             get
@@ -90,7 +92,7 @@ namespace System.Diagnostics
         }
 
         /// <summary>
-        /// Returns the value of the key-value pair added to the activity with 'WithBaggage'.
+        /// Returns the value of the key-value pair added to the activity with <see cref="AddBaggage(string, string)"/>.
         /// Returns null if that key does not exist.  
         /// </summary>
         public string GetBaggageItem(string key)
@@ -105,9 +107,9 @@ namespace System.Diagnostics
 
         /// <summary>
         /// Note that Activity has a 'builder' pattern, where you call the constructor, a number of 'With*' APIs and then
-        /// call 'Activity.Start' to build the activity.   You MUST call Start before using it 
+        /// call <see cref="Start"/> to build the activity.  You MUST call <see cref="Start"/> before using it.
         /// </summary>
-        /// <param name="operationName">Operations name <see cref="OperationName"/></param>
+        /// <param name="operationName">Operation's name <see cref="OperationName"/></param>
         public Activity(string operationName)
         {
             if (string.IsNullOrEmpty(operationName))
@@ -117,10 +119,10 @@ namespace System.Diagnostics
 
         /// <summary>
         /// Update the Activity to have a tag with an additional 'key' and value 'value'.
-        /// This shows up in the 'Tags' eumeration.   It is meant for information that
-        /// is useful to log but not needed for runtime control (for the latter, use Baggage)
+        /// This shows up in the <see cref="Tags"/>  eumeration.   It is meant for information that
+        /// is useful to log but not needed for runtime control (for the latter, <see cref="Baggage"/>)
         /// </summary>
-        /// <returns>'this' for convinient chaining</returns>
+        /// <returns>'this' for convenient chaining</returns>
         public Activity AddTag(string key, string value)
         {
             _tags = new KeyValueListNode() { keyValue = new KeyValuePair<string, string>(key, value), Next = _tags };
@@ -129,12 +131,13 @@ namespace System.Diagnostics
 
         /// <summary>
         /// Update the Activity to have baggage with an additional 'key' and value 'value'.
-        /// This shows up in the 'Baggage' eumeration as well as the 'GetBaggageItem' API.
-        /// Baggage is mean for information that is needed for runtime control.   For information 
-        /// that is simply useful to show up in the log with the activity use Tags.   
-        /// Returns 'this' for convinient chaining.
+        /// This shows up in the <see cref="Baggage"/> eumeration as well as the <see cref="GetBaggageItem(string)"/>
+        /// mathod.
+        /// Baggage is meant for information that is needed for runtime control.   For information 
+        /// that is simply useful to show up in the log with the activity use <see cref="Tags"/>.
+        /// Returns 'this' for convenient chaining.
         /// </summary>
-        /// <returns>'this' for convinient chaining</returns>
+        /// <returns>'this' for convenient chaining</returns>
         public Activity AddBaggage(string key, string value)
         {
             _baggage = new KeyValueListNode() { keyValue = new KeyValuePair<string, string>(key, value), Next = _baggage };
@@ -142,13 +145,14 @@ namespace System.Diagnostics
         }
 
         /// <summary>
-        /// Updates the Activity To indicate that the activity with ID 'parentID' 
-        /// caused this activity.   This is only intended to be used at 'boundary' 
-        /// scenarios where an activity from another process loggically started 
+        /// Updates the Activity To indicate that the activity with ID <paramref name="parentId"/>
+        /// caused this activity.   This is intended to be used only at 'boundary' 
+        /// scenarios where an activity from another process logically started 
         /// this activity. The Parent ID shows up the Tags (as well as the ParentID 
         /// property), and can be used to reconstruct the causal tree.  
-        /// Returns 'this' for convinient chaining.
+        /// Returns 'this' for convenient chaining.
         /// </summary>
+        /// <param name="parentId">The id of the parent operation.</param>
         public Activity SetParentId(string parentId)
         {
             if (Parent != null)
@@ -169,8 +173,8 @@ namespace System.Diagnostics
         /// <summary>
         /// Update the Activity to set start time
         /// </summary>
-        /// <param name="startTimeUtc">Activity start time in UTC (Greenwitch Mean Time)</param>
-        /// <returns>'this' for convinient chaining</returns>
+        /// <param name="startTimeUtc">Activity start time in UTC (Greenwich Mean Time)</param>
+        /// <returns>'this' for convenient chaining</returns>
         public Activity SetStartTime(DateTime startTimeUtc)
         {
             if (startTimeUtc.Kind != DateTimeKind.Utc)
@@ -181,10 +185,10 @@ namespace System.Diagnostics
         /// <summary>
         /// Update the Activity to set <see cref="Duration"/>
         /// as a difference between <see cref="StartTimeUtc"/>
-        /// and given stop timestamp
+        /// and <paramref name="endTimeUtc"/>.
         /// </summary>
-        /// <param name="endTimeUtc">Activity stop time in UTC (Greenwitch Mean Time)</param>
-        /// <returns>'this' for convinient chaining</returns>
+        /// <param name="endTimeUtc">Activity stop time in UTC (Greenwich Mean Time)</param>
+        /// <returns>'this' for convenient chaining</returns>
         public Activity SetEndTime(DateTime endTimeUtc)
         {
             if (endTimeUtc.Kind != DateTimeKind.Utc)
@@ -195,18 +199,22 @@ namespace System.Diagnostics
         }
 
         /// <summary>
-        /// If the Activity has ended (Stop was called) then this is the delta
+        /// If the Activity has ended (<see cref="Stop"/> was called) then this is the delta
         /// between start and end.   If the activity is not ended then this is 
-        /// TimeSpan.Zero.  
+        /// <see cref="TimeSpan.Zero"/>.
         /// </summary>
         public TimeSpan Duration { get; private set; }
 
         /// <summary>
-        /// Starts activity: sets <see cref="Parent"/> to hold <see cref="Current"/> and sets Current to this Activity.
-        /// If <see cref="StartTimeUtc"/> was not set previously, sets it to DateTime.UtcNow.
-        /// Use DiagnosticSource.Start to start activity and write start event.
+        /// Starts activity:
+        /// <list type="bullet">
+        /// <item>Sets <see cref="Parent"/> to hold <see cref="Current"/>.</item>
+        /// <item>Sets <see cref="Current"/> to this activity.</item>
+        /// <item>If <see cref="StartTimeUtc"/> was not set previously, sets it to <see cref="DateTime.UtcNow"/>.</item>
+        /// <item>Generates a unique <see cref="Id"/> for this activity.</item>
+        /// </list>
+        /// Use <see cref="DiagnosticSource.StartActivity(Activity, object)"/> to start activity and write start event.
         /// </summary>
-        /// <returns>Started activity for convinient chaining</returns>
         /// <seealso cref="DiagnosticSource.StartActivity(Activity, object)"/>
         /// <seealso cref="SetStartTime(DateTime)"/>
         public Activity Start()
@@ -234,9 +242,9 @@ namespace System.Diagnostics
         }
 
         /// <summary>
-        /// Stops activity: sets Current to Parent.
-        /// If end time was not set previously, sets <see cref="Duration"/> as a difference between DateTime.UtcNow and <see cref="StartTimeUtc"/>
-        /// Use DiagnosticSource.Stop to stop activity and write stop event.
+        /// Stops activity: sets <see cref="Current"/> to <see cref="Parent"/>.
+        /// If end time was not set previously, sets <see cref="Duration"/> as a difference between <see cref="DateTime.UtcNow"/> and <see cref="StartTimeUtc"/>
+        /// Use <see cref="DiagnosticSource.StopActivity(Activity, object)"/>  to stop activity and write stop event.
         /// </summary>
         /// <seealso cref="DiagnosticSource.StopActivity(Activity, object)"/>
         /// <seealso cref="SetEndTime(DateTime)"/>
diff --git a/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/DiagnosticSourceActivity.cs b/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/DiagnosticSourceActivity.cs
index 8ad372c81a..221cec7287 100644
--- a/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/DiagnosticSourceActivity.cs
+++ b/src/System.Diagnostics.DiagnosticSource/src/System/Diagnostics/DiagnosticSourceActivity.cs
@@ -11,7 +11,7 @@
         /// This method starts given Activity (maintains global Current Activity 
         /// and Parent for the given activity) and notifies consumers  that new Activity 
         /// was started. Consumers could access <see cref="Activity.Current"/>
-        /// to add context and/or augument telemetry.
+        /// to add context and/or augment telemetry.
         /// 
         /// Producers may pass additional details to the consumer in the payload.
         /// </summary>
@@ -29,7 +29,7 @@
         /// <summary>
         /// Stops given Activity: maintains global Current Activity and notifies consumers 
         /// that Activity was stopped. Consumers could access <see cref="Activity.Current"/>
-        /// to add context and/or augument telemetry.
+        /// to add context and/or augment telemetry.
         /// 
         /// Producers may pass additional details to the consumer in the payload.
         /// </summary>