Fixes #1750, changing description of productInformation param for clarity (#1751)

* Updated GitHubClient.cs XML Docs to match dev docs.

* Updated Connection.cs XML Docs to match dev docs.

* Updated ProductHeaderValue.cs XML Docs to match GitHub dev docs.

* Updated EnterpriseProbe.cs XML Docs to match GitHub dev docs.

* Updated GitHubClient.cs XML Docs to match GitHub dev docs, corrected grammar issue.

* Updated Connection.cs XML Docs to match GitHub dev docs, corrected grammar issue.

* Updated ProductHeaderValue.cs XML Docs to match GitHub dev docs, corrected grammar issue.

* Removed my tabs, replaced with spaces to match format.

* Removed tabs again

* There seems to be some kind of bug where tabs are being shown though my local editor show none, so I'm submitting a bug to GitHub.com and editing in-browser to fix.

* Update GitHubClient.cs

* There seems to be some kind of bug where tabs are being shown though my local editor show none, so I'm submitting a bug to GitHub.com and editing in-browser to fix.

* Update Connection.cs

* There seems to be some kind of bug where tabs are being shown though my local editor show none, so I'm submitting a bug to GitHub.com and editing in-browser to fix.

* Change a couple of tabs to spaces

* tabs to spaces

* tabs to spaces

Octokit/Clients/Enterprise/EnterpriseProbe.cs

@@ -19,9 +19,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new EnterpriseProbe, used to check for the existence of GitHub Enterprise Instances
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         [System.Diagnostics.CodeAnalysis.SuppressMessage("Microsoft.Reliability", "CA2000:Dispose objects before losing scope")]
         public EnterpriseProbe(ProductHeaderValue productInformation)
@@ -32,9 +35,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new EnterpriseProbe, used to check for the existence of GitHub Enterprise Instances
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="httpClient">
         /// The client to use for executing requests
@@ -60,7 +66,7 @@ namespace Octokit
         /// <see cref="EnterpriseProbeResult.NotFound"/>, or <see cref="EnterpriseProbeResult.Failed"/> in the case the request failed</returns>
         public async Task<EnterpriseProbeResult> Probe(Uri enterpriseBaseUrl)
         {
-            // This method should return NotFound if you happen to point it 
+            // This method should return NotFound if you happen to point it
             if (enterpriseBaseUrl.Host.Equals("github.com", StringComparison.OrdinalIgnoreCase)
                 || enterpriseBaseUrl.Host.Equals("api.github.com", StringComparison.OrdinalIgnoreCase))
                 throw new ArgumentException("This method should not be passed a github.com or api.github.com URL", "enterpriseBaseUrl");
@@ -114,7 +120,7 @@ namespace Octokit
         NotFound,
 
         /// <summary>
-        /// Request timed out or DNS failed. So it's probably the case it's not an enterprise server but 
+        /// Request timed out or DNS failed. So it's probably the case it's not an enterprise server but
         /// we can't know for sure.
         /// </summary>
         Failed

Octokit/GitHubClient.cs

@@ -15,12 +15,15 @@ namespace Octokit
         internal static readonly Uri GitHubDotComUrl = new Uri("https://github.com/");
 
         /// <summary>
-        /// Create a new instance of the GitHub API v3 client pointing to 
+        /// Create a new instance of the GitHub API v3 client pointing to
         /// https://api.github.com/
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         public GitHubClient(ProductHeaderValue productInformation)
             : this(new Connection(productInformation, GitHubApiUrl))
@@ -28,12 +31,15 @@ namespace Octokit
         }
 
         /// <summary>
-        /// Create a new instance of the GitHub API v3 client pointing to 
+        /// Create a new instance of the GitHub API v3 client pointing to
         /// https://api.github.com/
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="credentialStore">Provides credentials to the client when making requests</param>
         public GitHubClient(ProductHeaderValue productInformation, ICredentialStore credentialStore)
@@ -44,12 +50,15 @@ namespace Octokit
         /// <summary>
         /// Create a new instance of the GitHub API v3 client pointing to the specified baseAddress.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="baseAddress">
-        /// The address to point this client to. Typically used for GitHub Enterprise 
+        /// The address to point this client to. Typically used for GitHub Enterprise
         /// instances</param>
         public GitHubClient(ProductHeaderValue productInformation, Uri baseAddress)
             : this(new Connection(productInformation, FixUpBaseUri(baseAddress)))
@@ -59,13 +68,16 @@ namespace Octokit
         /// <summary>
         /// Create a new instance of the GitHub API v3 client pointing to the specified baseAddress.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="credentialStore">Provides credentials to the client when making requests</param>
         /// <param name="baseAddress">
-        /// The address to point this client to. Typically used for GitHub Enterprise 
+        /// The address to point this client to. Typically used for GitHub Enterprise
         /// instances</param>
         public GitHubClient(ProductHeaderValue productInformation, ICredentialStore credentialStore, Uri baseAddress)
             : this(new Connection(productInformation, FixUpBaseUri(baseAddress), credentialStore))
@@ -125,9 +137,9 @@ namespace Octokit
         /// Convenience property for getting and setting credentials.
         /// </summary>
         /// <remarks>
-        /// You can use this property if you only have a single hard-coded credential. Otherwise, pass in an 
-        /// <see cref="ICredentialStore"/> to the constructor. 
-        /// Setting this property will change the <see cref="ICredentialStore"/> to use 
+        /// You can use this property if you only have a single hard-coded credential. Otherwise, pass in an
+        /// <see cref="ICredentialStore"/> to the constructor.
+        /// Setting this property will change the <see cref="ICredentialStore"/> to use
         /// the default <see cref="InMemoryCredentialStore"/> with just these credentials.
         /// </remarks>
         public Credentials Credentials

Octokit/Http/Connection.cs

@@ -15,7 +15,7 @@ using System.Runtime.InteropServices;
 namespace Octokit
 {
     // NOTE: Every request method must go through the `RunRequest` code path. So if you need to add a new method
-    //       ensure it goes through there. :)
+    // ensure it goes through there. :)
     /// <summary>
     /// A connection for making HTTP requests against URI endpoints.
     /// </summary>
@@ -31,9 +31,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         public Connection(ProductHeaderValue productInformation)
             : this(productInformation, _defaultGitHubApiUrl, _anonymousCredentials)
@@ -43,9 +46,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="httpClient">
         /// The client to use for executing requests
@@ -58,9 +64,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="baseAddress">
         /// The address to point this client to such as https://api.github.com or the URL to a GitHub Enterprise
@@ -73,9 +82,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="credentialStore">Provides credentials to the client when making requests</param>
         public Connection(ProductHeaderValue productInformation, ICredentialStore credentialStore)
@@ -86,9 +98,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="baseAddress">
         /// The address to point this client to such as https://api.github.com or the URL to a GitHub Enterprise
@@ -103,9 +118,12 @@ namespace Octokit
         /// <summary>
         /// Creates a new connection instance used to make requests of the GitHub API.
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         /// <param name="productInformation">
-        /// The name (and optionally version) of the product using this library. This is sent to the server as part of
-        /// the user agent for analytics purposes.
+        /// The name (and optionally version) of the product using this library, the name of your GitHub organization, or your GitHub username (in that order of preference). This is sent to the server as part of
+        /// the user agent for analytics purposes, and used by GitHub to contact you if there are problems.
         /// </param>
         /// <param name="baseAddress">
         /// The address to point this client to such as https://api.github.com or the URL to a GitHub Enterprise

Octokit/Http/ProductHeaderValue.cs

@@ -2,20 +2,24 @@
 {
     /// <summary>
     /// Represents a product header value. This is used to generate the User Agent string sent with each request. The
-    /// name used should represent the product that's using Octokit.net.
+    /// name used should represent the product, the GitHub Organization, or the GitHub username that's using Octokit.net (in that order of preference).
     /// </summary>
     /// <remarks>
-    /// This class is a wrapper around <seealso href="https://msdn.microsoft.com/en-us/library/system.net.http.headers.productheadervalue(v=vs.118).aspx"/> 
+    /// This class is a wrapper around <seealso href="https://msdn.microsoft.com/en-us/library/system.net.http.headers.productheadervalue(v=vs.118).aspx"/>
     /// so that consumers of Octokit.net would not have to add a reference to the System.Net.Http.Headers namespace.
+    /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
     /// </remarks>
-    public class ProductHeaderValue
+  public class ProductHeaderValue
     {
         readonly System.Net.Http.Headers.ProductHeaderValue _productHeaderValue;
 
         /// <summary>
         /// Initializes a new instance of the <see cref="ProductHeaderValue"/> class.
         /// </summary>
-        /// <param name="name">The name of the product that's using Octokit</param>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
+        /// <param name="name">The name of the product, the GitHub Organization, or the GitHub Username (in that order of preference) that's using Octokit</param>
         public ProductHeaderValue(string name)
             : this(new System.Net.Http.Headers.ProductHeaderValue(name))
         {
@@ -24,7 +28,10 @@
         /// <summary>
         /// Initializes a new instance of the <see cref="ProductHeaderValue"/> class.
         /// </summary>
-        /// <param name="name">The name of the product that's using Octokit</param>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
+        /// <param name="name">The name of the product, the GitHub Organization, or the GitHub Username (in that order of preference) that's using Octokit</param>
         /// <param name="version">The version of the product that's using Octokit</param>
         public ProductHeaderValue(string name, string version)
             : this(new System.Net.Http.Headers.ProductHeaderValue(name, version))
@@ -37,8 +44,11 @@
         }
 
         /// <summary>
-        /// The name of the product that's using Octokit
+        /// The name of the product, the GitHub Organization, or the GitHub Username that's using Octokit (in that order of preference)
         /// </summary>
+        /// <remarks>
+        /// See more information regarding User-Agent requirements here: https://developer.github.com/v3/#user-agent-required
+        /// </remarks>
         public string Name
         {
             get { return _productHeaderValue.Name; }