Add xmldocs for GitHubContextService

Author: jcansdale

src/GitHub.App/Services/GitHubContextService.cs

@@ -66,12 +66,21 @@ public GitHubContextService(IGitHubServiceProvider serviceProvider, IGitService
             textManager = new Lazy<IVsTextManager2>(() => serviceProvider.GetService<SVsTextManager, IVsTextManager2>());
         }
 
+        /// <summary>
+        /// Find the context from a URL in the clipboard if any.
+        /// </summary>
+        /// <returns>The context or null if clipboard doesn't contain a GitHub URL</returns>
         public GitHubContext FindContextFromClipboard()
         {
             var text = Clipboard.GetText(TextDataFormat.Text);
             return FindContextFromUrl(text);
         }
 
+        /// <summary>
+        /// Convert a GitHub URL to a context object.
+        /// </summary>
+        /// <param name="url">A GitHub URL</param>
+        /// <returns>The context from the URL or null</returns>
         public GitHubContext FindContextFromUrl(string url)
         {
             var uri = new UriString(url);
@@ -117,6 +126,10 @@ public GitHubContext FindContextFromUrl(string url)
             return context;
         }
 
+        /// <summary>
+        /// Find the context from the title of the topmost browser.
+        /// </summary>
+        /// <returns>A context or null if a context can't be found.</returns>
         public GitHubContext FindContextFromBrowser()
         {
             return
@@ -126,31 +139,23 @@ public GitHubContext FindContextFromBrowser()
                 .FirstOrDefault();
         }
 
-        public IEnumerable<string> FindWindowTitlesForClass(string className = "MozillaWindowClass")
-        {
-            IntPtr handleWin = IntPtr.Zero;
-            while (IntPtr.Zero != (handleWin = User32.FindWindowEx(IntPtr.Zero, handleWin, className, IntPtr.Zero)))
-            {
-                // Allocate correct string length first
-                int length = User32.GetWindowTextLength(handleWin);
-                if (length == 0)
-                {
-                    continue;
-                }
-
-                var titleBuilder = new StringBuilder(length + 1);
-                User32.GetWindowText(handleWin, titleBuilder, titleBuilder.Capacity);
-                yield return titleBuilder.ToString();
-            }
-        }
-
+        /// <summary>
+        /// Convert a context to a repository URL.
+        /// </summary>
+        /// <param name="context">The context to convert.</param>
+        /// <returns>A repository URL</returns>
         public Uri ToRepositoryUrl(GitHubContext context)
         {
             var builder = new UriBuilder("https", context.Host ?? "github.com");
             builder.Path = $"{context.Owner}/{context.RepositoryName}";
             return builder.Uri;
         }
 
+        /// <summary>
+        /// Find a context from a browser window title.
+        /// </summary>
+        /// <param name="windowTitle">A browser window title.</param>
+        /// <returns>The context or null if none can be found</returns>
         public GitHubContext FindContextFromWindowTitle(string windowTitle)
         {
             var match = windowTitleBlobRegex.Match(windowTitle);
@@ -237,6 +242,12 @@ public GitHubContext FindContextFromWindowTitle(string windowTitle)
             return null;
         }
 
+        /// <summary>
+        /// Open a file in the working directory that corresponds to a context and navigate to a line/range.
+        /// </summary>
+        /// <param name="repositoryDir">The working directory.</param>
+        /// <param name="context">A context to navigate to.</param>
+        /// <returns>True if navigation was successful</returns>
         public bool TryOpenFile(string repositoryDir, GitHubContext context)
         {
             var (commitish, path, isSha) = ResolveBlob(repositoryDir, context);
@@ -251,6 +262,13 @@ public bool TryOpenFile(string repositoryDir, GitHubContext context)
             return true;
         }
 
+        /// <summary>
+        /// Map from a context to a repository blob object.
+        /// </summary>
+        /// <param name="repositoryDir">The target repository.</param>
+        /// <param name="context">The context to map from.</param>
+        /// <param name="remoteName">The name of the remote to search for branches.</param>
+        /// <returns>The resolved commit-ish, blob path and commit SHA for the blob. Path will be null if the commit-ish can be resolved but not the blob.</returns>
         public (string commitish, string path, string commitSha) ResolveBlob(string repositoryDir, GitHubContext context, string remoteName = "origin")
         {
             Guard.ArgumentNotNull(repositoryDir, nameof(repositoryDir));
@@ -316,6 +334,16 @@ public bool TryOpenFile(string repositoryDir, GitHubContext context)
             }
         }
 
+        /// <summary>
+        /// Check if a file in the working directory has changed since a specified commit-ish.
+        /// </summary>
+        /// <remarks>
+        /// The commit-ish might be a commit SHA, a tag or a remote branch.
+        /// </remarks>
+        /// <param name="repositoryDir">The target repository.</param>
+        /// <param name="commitish">A commit SHA, remote branch or tag.</param>
+        /// <param name="path">The path for a blob.</param>
+        /// <returns>True if the working file is different.</returns>
         public bool HasChangesInWorkingDirectory(string repositoryDir, string commitish, string path)
         {
             using (var repo = gitService.GetRepository(repositoryDir))
@@ -327,6 +355,17 @@ public bool HasChangesInWorkingDirectory(string repositoryDir, string commitish,
             }
         }
 
+        /// <summary>
+        /// Attempt to open the Blame/Annotate view for a context.
+        /// </summary>
+        /// <remarks>
+        /// The access to the Blame/Annotate view was added in a version of Visual Studio 2017. This method will return
+        /// false is this functionality isn't available.
+        /// </remarks>
+        /// <param name="repositoryDir">The target repository</param>
+        /// <param name="currentBranch">A branch in the local repository. It isn't displayed on the UI but must exist. It can be a remote or local branch.</param>
+        /// <param name="context">The context to open.</param>
+        /// <returns>True if AnnotateFile functionality is available.</returns>
         public async Task<bool> TryAnnotateFile(string repositoryDir, string currentBranch, GitHubContext context)
         {
             var (commitish, path, commitSha) = ResolveBlob(repositoryDir, context);
@@ -371,7 +410,7 @@ IVsTextView FindActiveView()
         /// <param name="branchName">A branch of the target repository</param>
         /// <param name="relativePath">A path the the target blob</param>
         /// <param name="versionSha">The commit version of the blob</param>
-        /// <returns></returns>
+        /// <returns>True if AnnotateFile functionality is available.</returns>
         bool AnnotateFile(string repositoryPath, string branchName, string relativePath, string versionSha)
         {
             var serviceType = Type.GetType("Microsoft.VisualStudio.TeamFoundation.Git.Extensibility.IGitExt2, Microsoft.TeamFoundation.Git.Provider", false);
@@ -485,6 +524,24 @@ static string FindSubPath(UriString gitHubUrl, string matchPath)
             return path;
         }
 
+        static IEnumerable<string> FindWindowTitlesForClass(string className)
+        {
+            IntPtr handleWin = IntPtr.Zero;
+            while (IntPtr.Zero != (handleWin = User32.FindWindowEx(IntPtr.Zero, handleWin, className, IntPtr.Zero)))
+            {
+                // Allocate correct string length first
+                int length = User32.GetWindowTextLength(handleWin);
+                if (length == 0)
+                {
+                    continue;
+                }
+
+                var titleBuilder = new StringBuilder(length + 1);
+                User32.GetWindowText(handleWin, titleBuilder, titleBuilder.Capacity);
+                yield return titleBuilder.ToString();
+            }
+        }
+
         static class User32
         {
             [DllImport("user32.dll", SetLastError = true)]

src/GitHub.Exports/Services/IGitHubContextService.cs

@@ -1,6 +1,5 @@
 using System;
 using System.Threading.Tasks;
-using System.Collections.Generic;
 
 namespace GitHub.Services
 {
@@ -10,7 +9,6 @@ public interface IGitHubContextService
         GitHubContext FindContextFromBrowser();
         GitHubContext FindContextFromUrl(string url);
         GitHubContext FindContextFromWindowTitle(string windowTitle);
-        IEnumerable<string> FindWindowTitlesForClass(string className);
         Uri ToRepositoryUrl(GitHubContext context);
         bool TryOpenFile(string repositoryDir, GitHubContext context);
         Task<bool> TryAnnotateFile(string repositoryDir, string currentBranch, GitHubContext context);