Support help links for items, properties, and tasks.

#5

help/elements.json

@@ -0,0 +1,50 @@
+{
+    "PropertyGroup": {
+        "description": "Contains a set of user-defined `Property` elements.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/propertygroup-element-msbuild"
+    },
+    "Item": {
+        "description": "Contains a user-defined item and its metadata.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/item-element-msbuild"
+    },
+    "ItemGroup": {
+        "description": "Contains a set of user-defined `Item` elements.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/itemgroup-element-msbuild"
+    },
+    "ItemDefinitionGroup": {
+        "description": "The `ItemDefinitionGroup` element lets you define a set of `Item` definitions, which are metadata values that are applied to all items in the project, by default.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/itemdefinitiongroup-element-msbuild"
+    },
+    "Choose": {
+        "description": "Evaluates child elements to select one set of `ItemGroup` elements and/or `PropertyGroup` elements to evaluate. ",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/choose-element-msbuild"
+    },
+    "When": {
+        "description": "Evaluates child `ItemGroup` and/or `PropertyGroup` elements when its `Condition` is true.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/choose-element-msbuild"
+    },
+    "Otherwise": {
+        "description": "Evaluates child `ItemGroup` and/or `PropertyGroup` elements when none of its sibling `When` elements has a `Condition` that is true.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/choose-element-msbuild"
+    },
+    "Output": {
+        "description": "Stores task output values in items and properties.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/output-element-msbuild"
+    },
+    "UsingTask": {
+        "description": "Maps the task that is referenced in a `Task` element to the assembly that contains the task implementation. ",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/usingtask-element-msbuild"
+    },
+    "Target": {
+        "description": "Contains a set of tasks for MSBuild to execute sequentially.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/target-element-msbuild"
+    },
+    "Import": {
+        "description": "Imports the contents of one project file into another project file.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/import-element-msbuild"
+    },
+    "ImportGroup": {
+        "description": "Contains a collection of `Import` elements that are grouped under an optional `Condition`.",
+        "help": "https://docs.microsoft.com/en-us/visualstudio/msbuild/importgroup-element"
+    }
+}

help/items.json

@@ -105,7 +105,8 @@
     "Content": {
         "description": "Files that are not compiled, but may be embedded or published",
         "metadata": {
-            "CopyToPublishDirectory": "Copy file to publish directory (optional, boolean, default false)",
+            "CopyToOutputDirectory": "Copy file to output directory (optional, Always|Newer|Never, default Never)",
+            "CopyToPublishDirectory": "Copy file to publish directory (optional, Always|Newer|Never, default Never)",
             "PublishState": "Default, Included, Excluded, DataFile, or Prerequisite"
         }
     },

help/properties.json

@@ -3,7 +3,11 @@
         "description": "Flag indicating whether to allow local network loopback."
     },
     "AllowUnsafeBlocks": {
-        "description": "Allow unsafe code blocks."
+        "description": "Allow unsafe code blocks.",
+        "defaultValues": [
+            "true",
+            "false"
+        ]
     },
     "AppDesignerFolder": {
         "description": "Name of folder for Application Designer"
@@ -473,6 +477,17 @@
     "InstallFrom": {
         "description": "Web, Unc, or Disk"
     },
+    "IsPackable": {
+        "description": "Enable or disable production of the project's NuGet package.",
+        "defaultValues": [
+            "true",
+            "false"
+        ]
+    },
+    "LangVersion": {
+        "description": "Which version of the target language (e.g. C# / VB) to use.",
+        "defaultValue": "latest"
+    },
     "LayoutDir": {
         "description": "Full path to a folder with package layout."
     },

src/LanguageServer.Common/Help/ItemHelp.cs

@@ -15,6 +15,12 @@ public class ItemHelp
         [JsonProperty("description")]
         public string Description { get; set; }
 
+        /// <summary>
+        ///     A link to the item type's documentation (if available).
+        /// </summary>
+        [JsonProperty("helpLink")]
+        public string HelpLink { get; set; }
+
         /// <summary>
         ///     Descriptions for the item's metadata.
         /// </summary>

src/LanguageServer.Common/Help/PropertyHelp.cs

@@ -15,6 +15,12 @@ public class PropertyHelp
         [JsonProperty("description")]
         public string Description { get; set; }
 
+        /// <summary>
+        ///     A link to the property's documentation (if available).
+        /// </summary>
+        [JsonProperty("helpLink")]
+        public string HelpLink { get; set; }
+
         /// <summary>
         ///     The property's default value.
         /// </summary>

src/LanguageServer.Common/Help/TaskHelp.cs

@@ -15,6 +15,12 @@ public class TaskHelp
         [JsonProperty("description")]
         public string Description { get; set; }
 
+        /// <summary>
+        ///     A link to the task's documentation (if available).
+        /// </summary>
+        [JsonProperty("helpLink")]
+        public string HelpLink { get; set; }
+
         /// <summary>
         ///     The task's parameters.
         /// </summary>
@@ -50,6 +56,12 @@ public class TaskParameterHelp
         [JsonProperty("description")]
         public string Description { get; set; }
 
+        /// <summary>
+        ///     A link to the task parameter's documentation (if available).
+        /// </summary>
+        [JsonProperty("helpLink")]
+        public string HelpLink { get; set; }
+
         /// <summary>
         ///     A description of the task parameter data-type.
         /// </summary>

src/LanguageServer.Engine/ContentProviders/HoverContentProvider.cs

@@ -91,6 +91,14 @@ public MarkedStringContainer Property(MSBuildProperty property)
             else
                 content.Add($"Value: `{property.Value}`");
 
+            string helpLink = MSBuildSchemaHelp.HelpLinkForProperty(property.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
+
             return new MarkedStringContainer(content);
         }
 
@@ -121,6 +129,14 @@ public MarkedStringContainer UnusedProperty(MSBuildUnusedProperty unusedProperty
                 $"Value would have been: `{unusedProperty.Value}`"
             );
 
+            string helpLink = MSBuildSchemaHelp.HelpLinkForProperty(unusedProperty.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
+
             return new MarkedStringContainer(content);
         }
 
@@ -142,6 +158,8 @@ public MarkedStringContainer ItemGroup(MSBuildItemGroup itemGroup)
             {
                 string packageVersion = itemGroup.GetFirstMetadataValue("Version");
 
+                // TODO: Verify package is from NuGet (later, we can also recognise MyGet)
+
                 return new MarkedStringContainer(
                     $"NuGet Package: [{itemGroup.FirstInclude}](https://nuget.org/packages/{itemGroup.FirstInclude}/{packageVersion})",
                     $"Version: {packageVersion}"
@@ -184,6 +202,14 @@ public MarkedStringContainer ItemGroup(MSBuildItemGroup itemGroup)
                 itemIncludeContent.ToString()
             );
 
+            string helpLink = MSBuildSchemaHelp.HelpLinkForItem(itemGroup.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
+
             return new MarkedStringContainer(content);  
         }
 
@@ -241,6 +267,14 @@ public MarkedStringContainer UnusedItemGroup(MSBuildUnusedItemGroup unusedItemGr
                 descriptionContent.ToString()
             );
 
+            string helpLink = MSBuildSchemaHelp.HelpLinkForItem(unusedItemGroup.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
+
             return new MarkedStringContainer(content);  
         }
 
@@ -335,6 +369,14 @@ public MarkedStringContainer ItemGroupMetadata(MSBuildItemGroup itemGroup, strin
                 metadataContent.ToString()
             );
 
+            string helpLink = MSBuildSchemaHelp.HelpLinkForItem(itemGroup.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
+
             return new MarkedStringContainer(content);
         }
 
@@ -417,8 +459,21 @@ public MarkedStringContainer Target(MSBuildTarget target)
         {
             if (target == null)
                 throw new ArgumentNullException(nameof(target));
+
+            List<MarkedString> content = new List<MarkedString>
+            {
+                $"Target: `{target.Name}`"
+            };
+
+            string helpLink = MSBuildSchemaHelp.HelpLinkForElement(target.Element.Name);
+            if (!String.IsNullOrWhiteSpace(helpLink))
+            {
+                content.Add(
+                    $"[Help]({helpLink})"
+                );
+            }
 
-            return $"Target: `{target.Name}`";
+            return new MarkedStringContainer(content);
         }
 
         /// <summary>

src/LanguageServer.SemanticModel.MSBuild/MSBuildSchemaHelp.cs

@@ -205,6 +205,48 @@ public static string HelpLinkForElement(string elementName)
             return null;
         }
 
+        /// <summary>
+        ///     Get a help link (if available) for the specified item.
+        /// </summary>
+        /// <param name="itemType">
+        ///     The item type name.
+        /// </param>
+        /// <returns>
+        ///     The item help link, or <c>null</c> if no link is available for it.
+        /// </returns>
+        public static string HelpLinkForItem(string itemType)
+        {
+            if (String.IsNullOrWhiteSpace(itemType))
+                throw new ArgumentException("Argument cannot be null, empty, or entirely composed of whitespace: 'itemName'.", nameof(itemType));
+
+            string helpKey = itemType;
+            if (ItemHelp.TryGetValue(helpKey, out ItemHelp help))
+                return help.HelpLink;
+
+            return null;
+        }
+
+        /// <summary>
+        ///     Get a help link (if available) for the specified property.
+        /// </summary>
+        /// <param name="propertyName">
+        ///     The property name.
+        /// </param>
+        /// <returns>
+        ///     The property help link, or <c>null</c> if no link is available for it.
+        /// </returns>
+        public static string HelpLinkForProperty(string propertyName)
+        {
+            if (String.IsNullOrWhiteSpace(propertyName))
+                throw new ArgumentException("Argument cannot be null, empty, or entirely composed of whitespace: 'propertyName'.", nameof(propertyName));
+
+            string helpKey = propertyName;
+            if (PropertyHelp.TryGetValue(helpKey, out PropertyHelp help))
+                return help.HelpLink;
+
+            return null;
+        }
+
         /// <summary>
         ///     Get help content for the specified attribute.
         /// </summary>

src/LanguageServer.SemanticModel.MSBuild/MSBuildUnusedProperty.cs

@@ -28,6 +28,11 @@ public MSBuildUnusedProperty(ProjectPropertyElement propertyElement, XSElement d
         /// </summary>
         public override string Name => PropertyElement.Name;
 
+        /// <summary>
+        ///     The <see cref="XSElement"/> that declares the property.
+        /// </summary>
+        public XSElement Element => (XSElement)base.Xml;
+
         /// <summary>
         ///     The kind of MSBuild object represented by the <see cref="MSBuildUnusedProperty"/>.
         /// </summary>