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

Repairing xml comments

Author: grokys

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);
     }
 }

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(

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,

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)
         {

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

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);

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>

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>

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();
     }

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

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>

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.

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;
 

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>

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);

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");
 

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,

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);
 

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,

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,

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>

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.

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,

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,

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)