Merge pull request #1846 from github/xml-doc-comments

grokys · web-flow · commit aeb7f7980ce2 · 2018-08-13T15:58:34.000+02:00
Repairing xml comments
diff --git a/src/GitHub.Api/ILoginManager.cs b/src/GitHub.Api/ILoginManager.cs
@@ -72,6 +72,7 @@ Task<User> LoginWithToken(
         /// Logs out of GitHub server.
         /// </summary>
         /// <param name="hostAddress">The address of the server.</param>
+        /// <param name="client">An octokit client configured to access the server.</param>
         Task Logout(HostAddress hostAddress, IGitHubClient client);
     }
 }
diff --git a/src/GitHub.Api/LoginManager.cs b/src/GitHub.Api/LoginManager.cs
@@ -34,8 +34,10 @@ public class LoginManager : ILoginManager
         /// </summary>
         /// <param name="keychain">The keychain in which to store credentials.</param>
         /// <param name="twoFactorChallengeHandler">The handler for 2FA challenges.</param>
+        /// <param name="oauthListener">The callback listener to signal successful login.</param>
         /// <param name="clientId">The application's client API ID.</param>
         /// <param name="clientSecret">The application's client API secret.</param>
+        /// <param name="scopes">List of scopes to authenticate for</param>
         /// <param name="authorizationNote">An note to store with the authorization.</param>
         /// <param name="fingerprint">The machine fingerprint.</param>
         public LoginManager(
diff --git a/src/GitHub.App/Extensions/AkavacheExtensions.cs b/src/GitHub.App/Extensions/AkavacheExtensions.cs
@@ -252,11 +252,12 @@ static IObservable<T> GetAndFetchLatestFromIndex<T>(this IBlobCache This,
         /// <typeparam name="T"></typeparam>
         /// <param name="blobCache">The cache to retrieve the object from.</param>
         /// <param name="key">The key to look up the cache value with.</param>
-        /// <param name="item">The item to add to the database</param>
+        /// <param name="fetchFunc">The fetch function.</param>
         /// <param name="maxCacheDuration">
         /// The maximum age of a cache object before the object is treated as
         /// expired and unusable. Cache objects older than this will be treated
         /// as a cache miss.
+        /// </param>
         /// <returns></returns>
         public static IObservable<T> PutAndUpdateIndex<T>(this IBlobCache blobCache,
             string key,
diff --git a/src/GitHub.App/Services/PullRequestEditorService.cs b/src/GitHub.App/Services/PullRequestEditorService.cs
@@ -336,6 +336,7 @@ public IVsTextView FindActiveView()
         /// <param name="fromLines">The document we're navigating from.</param>
         /// <param name="toLines">The document we're navigating to.</param>
         /// <param name="line">The 0-based line we're navigating from.</param>
+        /// <param name="matchLinesAbove"></param>
         /// <returns>The best matching line in <see cref="toLines"/></returns>
         public int FindMatchingLine(IList<string> fromLines, IList<string> toLines, int line, int matchLinesAbove = 0)
         {
diff --git a/src/GitHub.App/ViewModels/GitHubPane/PullRequestDetailViewModel.cs b/src/GitHub.App/ViewModels/GitHubPane/PullRequestDetailViewModel.cs
@@ -61,12 +61,13 @@ public sealed class PullRequestDetailViewModel : PanePageViewModelBase, IPullReq
         /// <summary>
         /// Initializes a new instance of the <see cref="PullRequestDetailViewModel"/> class.
         /// </summary>
-        /// <param name="localRepository">The local repository.</param>
-        /// <param name="modelService">The model service.</param>
         /// <param name="pullRequestsService">The pull requests service.</param>
         /// <param name="sessionManager">The pull request session manager.</param>
+        /// <param name="modelServiceFactory">The model service factory</param>
         /// <param name="usageTracker">The usage tracker.</param>
         /// <param name="teamExplorerContext">The context for tracking repo changes</param>
+        /// <param name="files">The view model which will display the changed files</param>
+        /// <param name="syncSubmodulesCommand">A command that will be run when <see cref="SyncSubmodules"/> is executed</param>
         [ImportingConstructor]
         public PullRequestDetailViewModel(
             IPullRequestService pullRequestsService,
@@ -200,6 +201,7 @@ public string TargetBranchDisplayName
             private set { this.RaiseAndSetIfChanged(ref targetBranchDisplayName, value); }
         }
 
+        /// <summary>
         /// Gets a value indicating whether the pull request branch is checked out.
         /// </summary>
         public bool IsCheckedOut
diff --git a/src/GitHub.App/ViewModels/GitHubPane/PullRequestDirectoryNode.cs b/src/GitHub.App/ViewModels/GitHubPane/PullRequestDirectoryNode.cs
@@ -12,7 +12,7 @@ public class PullRequestDirectoryNode : IPullRequestDirectoryNode
         /// <summary>
         /// Initializes a new instance of the <see cref="PullRequestDirectoryNode"/> class.
         /// </summary>
-        /// <param name="path">The path to the directory, relative to the repository.</param>
+        /// <param name="relativePath">The path to the directory, relative to the repository.</param>
         public PullRequestDirectoryNode(string relativePath)
         {
             DirectoryName = System.IO.Path.GetFileName(relativePath);
diff --git a/src/GitHub.Exports.Reactive/Services/IGitClient.cs b/src/GitHub.Exports.Reactive/Services/IGitClient.cs
@@ -110,6 +110,7 @@ public interface IGitClient
         /// </returns>
         Task<ContentChanges> CompareWith(IRepository repository, string sha1, string sha2, string path, byte[] contents);
 
+        /// <summary>
         /// Gets the value of a configuration key.
         /// </summary>
         /// <param name="repository">The repository.</param>
@@ -189,7 +190,7 @@ public interface IGitClient
         /// <summary>
         /// Find the merge base SHA between two commits.
         /// </summary>
-        /// <param name="repository">The repository.</param>
+        /// <param name="repo">The repository.</param>
         /// <param name="targetCloneUrl">The clone url of the PR target repo.</param>
         /// <param name="baseSha">The PR base SHA.</param>
         /// <param name="headSha">The PR head SHA.</param>
@@ -201,9 +202,10 @@ public interface IGitClient
         /// <exception cref="LibGit2Sharp.NotFoundException">Thrown when the merge base can't be found.</exception>
         Task<string> GetPullRequestMergeBase(IRepository repo, UriString targetCloneUrl, string baseSha, string headSha, string baseRef, int pullNumber);
 
+        /// <summary>
         /// Checks whether the current head is pushed to its remote tracking branch.
         /// </summary>
-        /// <param name="repository">The repository.</param>
+        /// <param name="repo">The repository.</param>
         /// <returns></returns>
         Task<bool> IsHeadPushed(IRepository repo);
 
@@ -212,7 +214,7 @@ public interface IGitClient
         /// <paramref name="baseBranch"/> and <paramref name="compareBranch"/> and returns their
         /// commit messages.
         /// </summary>
-        /// <param name="repository">The repository.</param>
+        /// <param name="repo">The repository.</param>
         /// <param name="baseBranch">The base branch to find a merge base with.</param>
         /// <param name="compareBranch">The compare branch to find a merge base with.</param>
         /// <param name="maxCommits">The maximum number of commits to return.</param>
diff --git a/src/GitHub.Exports.Reactive/Services/IPullRequestService.cs b/src/GitHub.Exports.Reactive/Services/IPullRequestService.cs
@@ -18,6 +18,7 @@ public interface IPullRequestService
         /// <param name="owner">The repository owner.</param>
         /// <param name="name">The repository name.</param>
         /// <param name="after">The end cursor of the previous page, or null for the first page.</param>
+        /// <param name="states">The pull request states to filter by</param>
         /// <returns>A page of pull request item models.</returns>
         Task<Page<PullRequestListItemModel>> ReadPullRequests(
             HostAddress address,
@@ -84,6 +85,7 @@ IObservable<IPullRequestModel> CreatePullRequest(IModelService modelService,
         /// Sync submodules on the current branch.
         /// </summary>
         /// <param name="repository">The repository.</param>
+        /// <param name="progress">A method that will be called with progress messages</param>
         Task<bool> SyncSubmodules(ILocalRepositoryModel repository, Action<string> progress);
 
         /// <summary>
diff --git a/src/GitHub.Exports.Reactive/Services/IPullRequestSession.cs b/src/GitHub.Exports.Reactive/Services/IPullRequestSession.cs
@@ -153,6 +153,7 @@ Task PostReviewComment(
 
         /// <summary>
         /// Refreshes the pull request session.
+        /// </summary>
         /// <returns>A task which completes when the session has completed refreshing.</returns>
         Task Refresh();
     }
diff --git a/src/GitHub.Exports.Reactive/Services/IPullRequestSessionManager.cs b/src/GitHub.Exports.Reactive/Services/IPullRequestSessionManager.cs
@@ -14,7 +14,7 @@ namespace GitHub.Services
     /// If the currently checked out branch represents a pull request then <see cref="CurrentSession"/>
     /// will return an <see cref="IPullRequestSession"/> containing the details of that pull request.
     /// A session for any other pull request can also be retrieved by calling
-    /// <see cref="GetSession(IPullRequestModel)"/>.
+    /// <see cref="GetSession(string, string, int)"/>.
     /// 
     /// Calling <see cref="GetLiveFile(string, ITextView, ITextBuffer)"/> will return an
     /// <see cref="IPullRequestSessionFile"/> which tracks both the contents of a text buffer and the
diff --git a/src/GitHub.Exports.Reactive/Services/IRepositoryCloneService.cs b/src/GitHub.Exports.Reactive/Services/IRepositoryCloneService.cs
@@ -23,7 +23,7 @@ public interface IRepositoryCloneService
         /// <param name="repositoryPath">The directory that will contain the repository directory.</param>
         /// <param name="progress">
         /// An object through which to report progress. This must be of type
-        /// <see cref="System.IProgress{Microsoft.VisualStudio.Shell.ServiceProgressData}"/>, but
+        /// System.IProgress&lt;Microsoft.VisualStudio.Shell.ServiceProgressData&gt;, but
         /// as that type is only available in VS2017+ it is typed as <see cref="object"/> here.
         /// </param>
         /// <returns></returns>
diff --git a/src/GitHub.Exports.Reactive/Services/IShowDialogService.cs b/src/GitHub.Exports.Reactive/Services/IShowDialogService.cs
@@ -35,6 +35,7 @@ public interface IShowDialogService
         /// The value returned by the <paramref name="viewModel"/>'s 
         /// <see cref="IDialogContentViewModel.Done"/> observable, or null if the dialog was
         /// canceled.
+        /// </returns>
         /// <remarks>
         /// The first existing connection will be used. If there is no existing connection, the
         /// login dialog will be shown first.
diff --git a/src/GitHub.Exports/Factories/IViewViewModelFactory.cs b/src/GitHub.Exports/Factories/IViewViewModelFactory.cs
@@ -13,7 +13,7 @@ public interface IViewViewModelFactory
         /// <summary>
         /// Creates a view model based on the specified interface type.
         /// </summary>
-        /// <typeparam name="T">The view model interface type.</typeparam>
+        /// <typeparam name="TViewModel">The view model interface type.</typeparam>
         /// <returns>The view model.</returns>
         TViewModel CreateViewModel<TViewModel>() where TViewModel : IViewModel;
 
diff --git a/src/GitHub.Exports/Models/ILocalRepositoryModel.cs b/src/GitHub.Exports/Models/ILocalRepositoryModel.cs
@@ -29,6 +29,7 @@ public interface ILocalRepositoryModel : IRepositoryModel, INotifyPropertyChange
         /// Generates a http(s) url to the repository in the remote server, optionally
         /// pointing to a specific file and specific line range in it.
         /// </summary>
+        /// <param name="linkType">The type of repository link to create</param>
         /// <param name="path">The file to generate an url to. Optional.</param>
         /// <param name="startLine">A specific line, or (if specifying the <paramref name="endLine"/> as well) the start of a range</param>
         /// <param name="endLine">The end of a line range on the specified file.</param>
diff --git a/src/GitHub.Exports/Services/IGitHubContextService.cs b/src/GitHub.Exports/Services/IGitHubContextService.cs
@@ -30,14 +30,14 @@ public interface IGitHubContextService
         /// <summary>
         /// Convert a context to a repository URL.
         /// </summary>
-        /// <param name="context">The context to convert.</param>
+        /// <param name="windowTitle">A browser window title.</param>
         /// <returns>A repository URL</returns>
         GitHubContext FindContextFromWindowTitle(string windowTitle);
 
         /// <summary>
         /// Find a context from a browser window title.
         /// </summary>
-        /// <param name="windowTitle">A browser window title.</param>
+        /// <param name="context"></param>
         /// <returns>The context or null if none can be found</returns>
         Uri ToRepositoryUrl(GitHubContext context);
 
@@ -78,7 +78,7 @@ public interface IGitHubContextService
         /// Team Explorer creates temporary blob files in the following format:
         /// C:\Users\me\AppData\Local\Temp\TFSTemp\vctmp21996_181282.IOpenFromClipboardCommand.783ac965.cs
         /// The object-ish appears immediately before the file extension and the path contains the folder "TFSTemp".
-        /// <remarks>
+        /// </remarks>
         /// <param name="tempFile">The path to a possible Team Explorer temporary blob file.</param>
         /// <returns>The target file's object-ish (blob SHA fragment) or null if the path isn't recognized as a Team Explorer blob file.</returns>
         string FindObjectishForTFSTempFile(string tempFile);
diff --git a/src/GitHub.Exports/Services/IGitService.cs b/src/GitHub.Exports/Services/IGitService.cs
@@ -12,6 +12,7 @@ public interface IGitService
         /// is null or no remote exists, this method returns null
         /// </summary>
         /// <param name="repository">The repository to look at for the remote.</param>
+        /// <param name="remote">The remote name to look for</param>
         /// <returns>A <see cref="UriString"/> representing the origin or null if none found.</returns>
         UriString GetUri(IRepository repository, string remote = "origin");
 
@@ -24,6 +25,7 @@ public interface IGitService
         /// walks up the parent directories until it either finds a repository, or reaches the root disk.
         /// </remarks>
         /// <param name="path">The path to start probing</param>
+        /// <param name="remote">The remote name to look for</param>
         /// <returns>A <see cref="UriString"/> representing the origin or null if none found.</returns>
         UriString GetUri(string path, string remote = "origin");
         
@@ -42,7 +44,8 @@ public interface IGitService
         /// <summary>
         /// Returns a <see cref="UriString"/> representing the uri of a remote.
         /// </summary>
-        /// <param name="repo"></param>
+        /// <param name="repo">The repository to look at for the remote.</param>
+        /// <param name="remote">The remote name to look for</param>
         /// <returns></returns>
         UriString GetRemoteUri(IRepository repo, string remote = "origin");
 
diff --git a/src/GitHub.Exports/Services/IVSGitServices.cs b/src/GitHub.Exports/Services/IVSGitServices.cs
@@ -17,9 +17,11 @@ public interface IVSGitServices
         /// <param name="recurseSubmodules">Whether to recursively clone submodules.</param>
         /// <param name="progress">
         /// An object through which to report progress. This must be of type
-        /// <see cref="System.IProgress{Microsoft.VisualStudio.Shell.ServiceProgressData}"/>, but
+        /// System.IProgress&lt;Microsoft.VisualStudio.Shell.ServiceProgressData&gt;, but
         /// as that type is only available in VS2017+ it is typed as <see cref="object"/> here.
         /// </param>
+        /// <seealso cref="System.IProgress{T}"/>
+        /// <seealso cref="Microsoft.VisualStudio.Shell.ServiceProgressData"/>
         Task Clone(
             string cloneUrl,
             string clonePath,
diff --git a/src/GitHub.Exports/Services/IVSServices.cs b/src/GitHub.Exports/Services/IVSServices.cs
@@ -16,7 +16,7 @@ public interface IVSServices
         /// Our workaround is to create, open and delete a solution in the repo directory.
         /// This triggers an event that causes the target repo to open. ;)
         /// </remarks>
-        /// <param name="repoPath">The path to the repository to open</param>
+        /// <param name="directory">The path to the repository to open</param>
         /// <returns>True if a transient solution was successfully created in target directory (which should trigger opening of repository).</returns>
         bool TryOpenRepository(string directory);
 
diff --git a/src/GitHub.InlineReviews/Commands/InlineCommentNavigationCommand.cs b/src/GitHub.InlineReviews/Commands/InlineCommentNavigationCommand.cs
@@ -34,6 +34,7 @@ abstract class InlineCommentNavigationCommand : VsCommand<InlineCommentNavigatio
         /// <summary>
         /// Initializes a new instance of the <see cref="InlineCommentNavigationCommand"/> class.
         /// </summary>
+        /// <param name="serviceProvider"></param>
         /// <param name="tagAggregatorFactory">The tag aggregator factory.</param>
         /// <param name="peekService">The peek service.</param>
         /// <param name="commandSet">The GUID of the group the command belongs to.</param>
@@ -74,7 +75,7 @@ protected int GetCursorPoint(ITextView textView, InlineCommentNavigationParams p
         /// <summary>
         /// Gets the text buffer position for the specified line.
         /// </summary>
-        /// <param name="parameter">The parameters.</param>
+        /// <param name="textView">The text view containing the buffer</param>
         /// <param name="lineNumber">The 0-based line number.</param>
         /// <returns></returns>
         protected int GetCursorPoint(ITextView textView, int lineNumber)
@@ -217,7 +218,10 @@ protected IReadOnlyList<ITagInfo> GetTags(IEnumerable<ITextView> textViews)
         /// <summary>
         /// Shows the inline comments for the specified tag in a peek view.
         /// </summary>
-        /// <param name="tag"></param>
+        /// <param name="textView">The text view containing the tag</param>
+        /// <param name="tag">The inline comment tag</param>
+        /// <param name="parameter">The navigation parameter detailing a search from the specified tag</param>
+        /// <param name="allTextViews">The full list of text views</param>
         protected void ShowPeekComments(
             InlineCommentNavigationParams parameter,
             ITextView textView,
diff --git a/src/GitHub.InlineReviews/Models/InlineCommentThreadModel.cs b/src/GitHub.InlineReviews/Models/InlineCommentThreadModel.cs
@@ -20,12 +20,10 @@ class InlineCommentThreadModel : ReactiveObject, IInlineCommentThreadModel
         /// </summary>
         /// <param name="relativePath">The relative path to the file that the thread is on.</param>
         /// <param name="commitSha">The SHA of the commit that the thread appears on.</param>
-        /// <param name="originalPosition">
-        /// The 1-based line number in the original diff that the thread was left on.
-        /// </param>
         /// <param name="diffMatch">
         /// The last five lines of the thread's diff hunk, in reverse order.
         /// </param>
+        /// <param name="comments">The comments in the thread</param>
         public InlineCommentThreadModel(
             string relativePath,
             string commitSha,
diff --git a/src/GitHub.InlineReviews/Services/IDiffService.cs b/src/GitHub.InlineReviews/Services/IDiffService.cs
@@ -27,7 +27,7 @@ public interface IDiffService
         /// </summary>
         /// <param name="repo">The repository</param>
         /// <param name="baseSha">The base commit SHA.</param>
-        /// <param name="headSha">The head commit SHA.</param
+        /// <param name="headSha">The head commit SHA.</param>
         /// <param name="relativePath">The path to the file in the repository.</param>
         /// <param name="contents">The byte array to compare with the base SHA.</param>
         /// <returns>
diff --git a/src/GitHub.InlineReviews/Services/IInlineCommentPeekService.cs b/src/GitHub.InlineReviews/Services/IInlineCommentPeekService.cs
@@ -15,6 +15,7 @@ public interface IInlineCommentPeekService
         /// Gets the line number for a peek session tracking point.
         /// </summary>
         /// <param name="session">The peek session.</param>
+        /// <param name="point">The peek session tracking point</param>
         /// <returns>
         /// A tuple containing the line number and whether the line number represents a line in the
         /// left hand side of a diff view.
diff --git a/src/GitHub.InlineReviews/Services/PullRequestSessionManager.cs b/src/GitHub.InlineReviews/Services/PullRequestSessionManager.cs
@@ -42,7 +42,7 @@ public class PullRequestSessionManager : ReactiveObject, IPullRequestSessionMana
         /// </summary>
         /// <param name="service">The PR service to use.</param>
         /// <param name="sessionService">The PR session service to use.</param>
-        /// <param name="teamExplorerService">The team explorer service to use.</param>
+        /// <param name="teamExplorerContext">The team explorer context to use.</param>
         [ImportingConstructor]
         public PullRequestSessionManager(
             IPullRequestService service,
diff --git a/src/GitHub.InlineReviews/ViewModels/PullRequestReviewCommentViewModel.cs b/src/GitHub.InlineReviews/ViewModels/PullRequestReviewCommentViewModel.cs
@@ -88,6 +88,7 @@ public PullRequestReviewCommentViewModel(
         /// <param name="commentService">Comment Service</param>
         /// <param name="thread">The thread that the comment is a part of.</param>
         /// <param name="currentUser">The current user.</param>
+        /// <param name="review">The associated pull request review.</param>
         /// <param name="model">The comment model.</param>
         public PullRequestReviewCommentViewModel(
             IPullRequestSession session,
diff --git a/src/GitHub.Services.Vssdk/Commands/MenuCommandServiceExtensions.cs b/src/GitHub.Services.Vssdk/Commands/MenuCommandServiceExtensions.cs
@@ -16,7 +16,7 @@ public static class MenuCommandServiceExtensions
         /// Adds <see cref="IVsCommand"/>s or <see cref="IVsCommand{TParam}"/>s to a menu.
         /// </summary>
         /// <param name="service">The menu command service.</param>
-        /// <param name="command">The commands to add.</param>
+        /// <param name="commands">The commands to add.</param>
         public static void AddCommands(
             this IMenuCommandService service,
             params IVsCommandBase[] commands)
diff --git a/src/GitHub.TeamFoundation.14/Base/TeamExplorerServiceHolder.cs b/src/GitHub.TeamFoundation.14/Base/TeamExplorerServiceHolder.cs

Original file line number	Diff line number	Diff line change
`@@ -72,6 +72,7 @@ Task<User> LoginWithToken(`
`72`	`72`	`/// Logs out of GitHub server.`
`73`	`73`	`/// </summary>`
`74`	`74`	`/// <param name="hostAddress">The address of the server.</param>`
	`75`	`+ /// <param name="client">An octokit client configured to access the server.</param>`
`75`	`76`	`Task Logout(HostAddress hostAddress, IGitHubClient client);`
`76`	`77`	`}`
`77`	`78`	`}`
Original file line number	Diff line number	Diff line change
`@@ -336,6 +336,7 @@ public IVsTextView FindActiveView()`
`336`	`336`	`/// <param name="fromLines">The document we're navigating from.</param>`
`337`	`337`	`/// <param name="toLines">The document we're navigating to.</param>`
`338`	`338`	`/// <param name="line">The 0-based line we're navigating from.</param>`
	`339`	`+ /// <param name="matchLinesAbove"></param>`
`339`	`340`	`/// <returns>The best matching line in <see cref="toLines"/></returns>`
`340`	`341`	`public int FindMatchingLine(IList<string> fromLines, IList<string> toLines, int line, int matchLinesAbove = 0)`
`341`	`342`	`{`
Original file line number	Diff line number	Diff line change
`@@ -12,7 +12,7 @@ public class PullRequestDirectoryNode : IPullRequestDirectoryNode`
`12`	`12`	`/// <summary>`
`13`	`13`	`/// Initializes a new instance of the <see cref="PullRequestDirectoryNode"/> class.`
`14`	`14`	`/// </summary>`
`15`		`- /// <param name="path">The path to the directory, relative to the repository.</param>`
	`15`	`+ /// <param name="relativePath">The path to the directory, relative to the repository.</param>`
`16`	`16`	`public PullRequestDirectoryNode(string relativePath)`
`17`	`17`	`{`
`18`	`18`	`DirectoryName = System.IO.Path.GetFileName(relativePath);`
Original file line number	Diff line number	Diff line change
`@@ -153,6 +153,7 @@ Task PostReviewComment(`
`153`	`153`
`154`	`154`	`/// <summary>`
`155`	`155`	`/// Refreshes the pull request session.`
	`156`	`+ /// </summary>`
`156`	`157`	`/// <returns>A task which completes when the session has completed refreshing.</returns>`
`157`	`158`	`Task Refresh();`
`158`	`159`	`}`