Add more xmldocs

Author: jcansdale

src/GitHub.App/Services/GitHubContextService.cs

@@ -20,6 +20,7 @@
 
 namespace GitHub.Services
 {
+    /// <inheritdoc/>
     [Export(typeof(IGitHubContextService))]
     public class GitHubContextService : IGitHubContextService
     {

src/GitHub.Exports/Commands/IOpenFromClipboardCommand.cs

@@ -1,5 +1,17 @@
 namespace GitHub.Commands
 {
+    /// <summary>
+    /// This command appears as `Code context > GitHub > Open from clipboard`.
+    /// 
+    /// Open a working directory file at the same location as a GitHub URL in the clipboard. If the URL links to
+    /// a line or range of lines, these lines will be selected. If the working directory file is different to the
+    /// target file, the target file will be opened in the `Blame (Annotate)` view. If the URL is from a different
+    /// fork, it will still open the target file assuming that the target commit/branch exists.
+    /// </summary>
+    /// <remarks>
+    /// Currently only GitHub `blob` URLs are supported. In a future version we can add support for `pull`, `issue`,
+    /// `tree`, `commits`, `blame` and any other URL types that might make sense.
+    /// </remarks>
     public interface IOpenFromClipboardCommand : IVsCommand<string>
     {
     }

src/GitHub.Exports/Commands/IOpenFromUrlCommand.cs

@@ -1,5 +1,13 @@
 namespace GitHub.Commands
 {
+    /// <summary>
+    /// This appears as the named command `GitHub.OpenFromUrl` and must be bound to a keyboard shortcut or executed
+    /// via the `Command Window`. In future it will appear on `File > Open > Open from GitHub`.
+    /// 
+    /// When executed it will offer to clone, open and navigate to the file pointed to by a URL in the clipboard.
+    /// This spike uses Yes/No/Cancel dialogs, but the final version will use a UI to control what action is performed
+    /// and allow the user to override the default repository location.
+    /// </summary>
     public interface IOpenFromUrlCommand : IVsCommand<string>
     {
     }

src/GitHub.Exports/Services/IGitHubContextService.cs

@@ -5,14 +5,79 @@ namespace GitHub.Services
 {
     public interface IGitHubContextService
     {
+        /// <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>
         GitHubContext FindContextFromClipboard();
+
+        /// <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>
         GitHubContext FindContextFromBrowser();
+
+        /// <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>
         GitHubContext FindContextFromUrl(string url);
+
+        /// <summary>
+        /// Convert a context to a repository URL.
+        /// </summary>
+        /// <param name="context">The context to convert.</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>
+        /// <returns>The context or null if none can be found</returns>
         Uri ToRepositoryUrl(GitHubContext context);
+
+        /// <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>
         bool TryOpenFile(string repositoryDir, GitHubContext context);
+
+        /// <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>
         Task<bool> TryAnnotateFile(string repositoryDir, string currentBranch, GitHubContext context);
+
+        /// <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>
         (string commitish, string path, string commitSha) ResolveBlob(string repositoryDir, GitHubContext context, string remoteName = "origin");
+
+        /// <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>
         bool HasChangesInWorkingDirectory(string repositoryDir, string commitish, string path);
     }
 }

src/GitHub.Exports/Services/IVSServices.cs

@@ -4,8 +4,27 @@ namespace GitHub.Services
 {
     public interface IVSServices
     {
+        /// <summary>
+        /// Get the full Visual Studio version from `VisualStudio\14.0_Config\SplashInfo|EnvVersion` on Visual Studoi 2015
+        /// or `SetupConfiguration.GetInstanceForCurrentProcess()` on on Visual Studoi 2017.
+        /// </summary>
         string VSVersion { get; }
+
+        /// <summary>Open a repository in Team Explorer</summary>
+        /// <remarks>
+        /// There doesn't appear to be a command that directly opens a target repo.
+        /// 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>
+        /// <returns>True if a transient solution was successfully created in target directory (which should trigger opening of repository).</returns>
         bool TryOpenRepository(string directory);
+
+        /// <summary>
+        /// Displays a message box with the specified message.
+        /// </summary>
+        /// <param name="message">The message to display</param>
+        /// <returns>The result.</returns>
         VSConstants.MessageBoxResult ShowMessageBoxInfo(string message);
     }
 }

src/GitHub.VisualStudio/Commands/OpenFromClipboardCommand.cs

@@ -9,6 +9,7 @@
 
 namespace GitHub.VisualStudio.Commands
 {
+    /// <inheritdoc/>
     [Export(typeof(IOpenFromClipboardCommand))]
     public class OpenFromClipboardCommand : VsCommand<string>, IOpenFromClipboardCommand
     {

src/GitHub.VisualStudio/Commands/OpenFromUrlCommand.cs

@@ -15,6 +15,7 @@
 
 namespace GitHub.VisualStudio.Commands
 {
+    /// <inheritdoc/>
     [Export(typeof(IOpenFromUrlCommand))]
     public class OpenFromUrlCommand : VsCommand<string>, IOpenFromUrlCommand
     {