Clarifies usage of reference in IReferencesClient methods (#1778)

* Clairifies usage of IReferencesClient.Delete Details the format of the reference parameter * update xml doc in all the places
octokit · Apr 23, 2018 · e51cc45 · e51cc45
1 parent 600c865
commit e51cc45
Show file tree

Hide file tree

Showing 4 changed files with 24 additions and 24 deletions.
diff --git a/Octokit.Reactive/Clients/IObservableReferencesClient.cs b/Octokit.Reactive/Clients/IObservableReferencesClient.cs
@@ -20,7 +20,7 @@ public interface IObservableReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
             Justification = "Method makes a network request")]
@@ -33,7 +33,7 @@ public interface IObservableReferencesClient
         /// http://developer.github.com/v3/git/refs/#get-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
             Justification = "Method makes a network request")]
@@ -162,7 +162,7 @@ public interface IObservableReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         IObservable<Reference> Update(string owner, string name, string reference, ReferenceUpdate referenceUpdate);
@@ -174,7 +174,7 @@ public interface IObservableReferencesClient
         /// http://developer.github.com/v3/git/refs/#update-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         IObservable<Reference> Update(long repositoryId, string reference, ReferenceUpdate referenceUpdate);
@@ -187,7 +187,7 @@ public interface IObservableReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         IObservable<Unit> Delete(string owner, string name, string reference);
 
@@ -198,7 +198,7 @@ public interface IObservableReferencesClient
         /// http://developer.github.com/v3/git/refs/#delete-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         IObservable<Unit> Delete(long repositoryId, string reference);
     }

diff --git a/Octokit.Reactive/Clients/ObservableReferencesClient.cs b/Octokit.Reactive/Clients/ObservableReferencesClient.cs
@@ -32,7 +32,7 @@ public ObservableReferencesClient(IGitHubClient client)
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public IObservable<Reference> Get(string owner, string name, string reference)
         {
@@ -50,7 +50,7 @@ public IObservable<Reference> Get(string owner, string name, string reference)
         /// http://developer.github.com/v3/git/refs/#get-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public IObservable<Reference> Get(long repositoryId, string reference)
         {
@@ -232,7 +232,7 @@ public IObservable<Reference> Create(long repositoryId, NewReference reference)
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         public IObservable<Reference> Update(string owner, string name, string reference, ReferenceUpdate referenceUpdate)
@@ -252,7 +252,7 @@ public IObservable<Reference> Update(string owner, string name, string reference
         /// http://developer.github.com/v3/git/refs/#update-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         public IObservable<Reference> Update(long repositoryId, string reference, ReferenceUpdate referenceUpdate)
@@ -271,7 +271,7 @@ public IObservable<Reference> Update(long repositoryId, string reference, Refere
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public IObservable<Unit> Delete(string owner, string name, string reference)
         {
@@ -289,7 +289,7 @@ public IObservable<Unit> Delete(string owner, string name, string reference)
         /// http://developer.github.com/v3/git/refs/#delete-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public IObservable<Unit> Delete(long repositoryId, string reference)
         {

diff --git a/Octokit/Clients/IReferencesClient.cs b/Octokit/Clients/IReferencesClient.cs
@@ -20,7 +20,7 @@ public interface IReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
              Justification = "Method makes a network request")]
@@ -33,7 +33,7 @@ public interface IReferencesClient
         /// http://developer.github.com/v3/git/refs/#get-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         [SuppressMessage("Microsoft.Naming", "CA1716:IdentifiersShouldNotMatchKeywords", MessageId = "Get",
              Justification = "Method makes a network request")]
@@ -162,7 +162,7 @@ public interface IReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         Task<Reference> Update(string owner, string name, string reference, ReferenceUpdate referenceUpdate);
@@ -174,7 +174,7 @@ public interface IReferencesClient
         /// http://developer.github.com/v3/git/refs/#update-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         Task<Reference> Update(long repositoryId, string reference, ReferenceUpdate referenceUpdate);
@@ -187,7 +187,7 @@ public interface IReferencesClient
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         Task Delete(string owner, string name, string reference);
 
@@ -198,7 +198,7 @@ public interface IReferencesClient
         /// http://developer.github.com/v3/git/refs/#delete-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         Task Delete(long repositoryId, string reference);
     }

diff --git a/Octokit/Clients/ReferencesClient.cs b/Octokit/Clients/ReferencesClient.cs
@@ -28,7 +28,7 @@ public ReferencesClient(IApiConnection apiConnection) :
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public Task<Reference> Get(string owner, string name, string reference)
         {
@@ -46,7 +46,7 @@ public Task<Reference> Get(string owner, string name, string reference)
         /// http://developer.github.com/v3/git/refs/#get-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public Task<Reference> Get(long repositoryId, string reference)
         {
@@ -232,7 +232,7 @@ public Task<Reference> Create(long repositoryId, NewReference reference)
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         public Task<Reference> Update(string owner, string name, string reference, ReferenceUpdate referenceUpdate)
@@ -252,7 +252,7 @@ public Task<Reference> Update(string owner, string name, string reference, Refer
         /// http://developer.github.com/v3/git/refs/#update-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <param name="referenceUpdate">The updated reference data</param>
         /// <returns></returns>
         public Task<Reference> Update(long repositoryId, string reference, ReferenceUpdate referenceUpdate)
@@ -271,7 +271,7 @@ public Task<Reference> Update(long repositoryId, string reference, ReferenceUpda
         /// </remarks>
         /// <param name="owner">The owner of the repository</param>
         /// <param name="name">The name of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public Task Delete(string owner, string name, string reference)
         {
@@ -289,7 +289,7 @@ public Task Delete(string owner, string name, string reference)
         /// http://developer.github.com/v3/git/refs/#delete-a-reference
         /// </remarks>
         /// <param name="repositoryId">The Id of the repository</param>
-        /// <param name="reference">The name of the reference</param>
+        /// <param name="reference">The canonical name of the reference without the 'refs/' prefix. e.g. "heads/master" or "tags/release-1"</param>
         /// <returns></returns>
         public Task Delete(long repositoryId, string reference)
         {