Merge pull request #216 from mhutch/update-readme

Update README and fix some schemas
mhutch · Apr 26, 2024 · 2ab1b3e · 2ab1b3e
2 parents 21b91d4 + 77112e7
commit 2ab1b3e
Show file tree

Hide file tree

Showing 3 changed files with 42 additions and 46 deletions.
diff --git a/MonoDevelop.MSBuild/Schemas/CommonTargets.buildschema.json b/MonoDevelop.MSBuild/Schemas/CommonTargets.buildschema.json
@@ -829,7 +829,7 @@
       "helpUrl": "https://learn.microsoft.com/dotnet/csharp/language-reference/compiler-options/resources#nowin32manifest"
     },
     "Win32Icon": {
-      "description": "A `.ico` icon file to be inserted into the compiled assembly to customize its appeance in File Explorer",
+      "description": "A `.ico` icon file to be inserted into the compiled assembly to customize its appearance in File Explorer",
       "type": "file",
       "helpUrl": "https://learn.microsoft.com/dotnet/csharp/language-reference/compiler-options/resources#win32icon"
     },

diff --git a/MonoDevelop.MSBuild/Schemas/buildschema.json b/MonoDevelop.MSBuild/Schemas/buildschema.json
@@ -1,5 +1,6 @@
 {
   "$id": "https://github.com/mhutch/MonoDevelop.MSBuildEditor",
+  "$comment": "This should be draft-07, but anything newer than draft-04 (or https) causes VS to error out when using the schema to validate other JSON files",
   "$schema": "http://json-schema.org/draft-04/schema#",
   "description": "Describes the MSBuild schema format",
   "type": "object",
@@ -30,7 +31,7 @@
     "intellisenseImports": {
       "type": "array",
       "items": { "type": "string" },
-      "description": "Additional files to be imported at development time for IntelliSense"
+      "description": "Additional schemas to be imported only when directly editing the file for which this schema is a sidecar."
     },
     "types": {
       "type": "object",
@@ -71,14 +72,8 @@
               "type": "boolean",
               "default": false
             },
-            "deprecationMessage": {
-              "type": "string",
-              "description": "Indicates that the property is deprecated and explains why."
-            },
-            "helpUrl": {
-              "type": "string",
-              "description": "Documentation link to be displayed in UI."
-            }
+            "deprecationMessage": { "$ref": "#/definitions/deprecationMessage" },
+            "helpUrl": { "$ref": "#/definitions/helpUrl" }
           },
           "additionalProperties": false
         }
@@ -118,14 +113,8 @@
               "type": "boolean",
               "default": false
             },
-            "deprecationMessage": {
-              "type": "string",
-              "description": "Indicates that the item is deprecated and explains why."
-            },
-            "helpUrl": {
-              "type": "string",
-              "description": "Documentation link to be displayed in UI."
-            }
+            "deprecationMessage": { "$ref": "#/definitions/deprecationMessage" },
+            "helpUrl": { "$ref": "#/definitions/helpUrl" }
           },
           "additionalProperties": false
         }
@@ -154,14 +143,8 @@
               "description": "Whether this metadata is required on items of this type",
               "type": "boolean"
             },
-            "deprecationMessage": {
-              "type": "string",
-              "description": "Indicates that the metadata is deprecated and explains why."
-            },
-            "helpUrl": {
-              "type": "string",
-              "description": "Documentation link to be displayed in UI."
-            }
+            "deprecationMessage": { "$ref": "#/definitions/deprecationMessage" },
+            "helpUrl": { "$ref": "#/definitions/helpUrl" }
           },
           "additionalProperties": false
         }
@@ -180,14 +163,8 @@
               "type": "string",
               "description": "Description of the target"
             },
-            "deprecationMessage": {
-              "type": "string",
-              "description": "Indicates that the target is deprecated and explains why."
-            },
-            "helpUrl": {
-              "type": "string",
-              "description": "Documentation link to be displayed in UI."
-            }
+            "deprecationMessage": { "$ref": "#/definitions/deprecationMessage" },
+            "helpUrl": { "$ref": "#/definitions/helpUrl" }
           },
           "additionalProperties": false
         }
@@ -229,7 +206,7 @@
       "enum": [ ";", ",", ";," ],
       "default": ";"
     },
-    "valueType" : {
+    "valueType": {
       "description": "The type of the value",
       "oneOf": [
         { "$ref": "#/definitions/valueTypeRef" },
@@ -238,7 +215,7 @@
         { "$ref": "#/definitions/valueTypeCustom" }
       ]
     },
-    "valueTypeDefinition" : {
+    "valueTypeDefinition": {
       "oneOf": [
         { "$ref": "#/definitions/valueTypeCustomMinimal" },
         { "$ref": "#/definitions/valueTypeCustom" }
@@ -263,7 +240,7 @@
       "type": "object",
       "properties": {
         "name": {
-          "description": "Overrides the name displayed in the UI",
+          "description": "Overrides the name displayed for this type in the UI. If not provided, falls back to the name of the `baseType`, otherwise the type is displayed as an anonymous type.",
           "type": "string",
           "pattern": "^([a-z][a-z\\d-]*)$"
         },
@@ -287,14 +264,8 @@
                     "type": "string",
                     "description": "Description of the value"
                   },
-                  "deprecationMessage": {
-                    "type": "string",
-                    "description": "Indicates that the property is deprecated and explains why."
-                  },
-                  "helpUrl": {
-                    "type": "string",
-                    "description": "Documentation link to be displayed in UI for all values of this type."
-                  },
+                  "deprecationMessage": { "$ref": "#/definitions/deprecationMessage" },
+                  "helpUrl": { "$ref": "#/definitions/helpUrl" },
                   "aliases": {
                     "type": "array",
                     "items": { "type": "string" },
@@ -491,8 +462,23 @@
         {
           "const": "clr-type-name",
           "description": "An unqualified .NET type name"
+        },
+        {
+          "const": "warning-code",
+          "description": "A warning code from the compiler, analyzers, MSBuild, etc."
         }
       ]
+    },
+    "deprecationMessage": {
+      "type": "string",
+      "description": "Indicates that the symbol is deprecated and explains why.",
+      "minLength": 1
+    },
+    "helpUrl": {
+      "type": "string",
+      "description": "Documentation link to be displayed in UI.",
+      "minLength": 1,
+      "format": "uri"
     }
   }
 }
diff --git a/README.md b/README.md
@@ -5,14 +5,22 @@
 
 MSBuild Editor is an open-source language service that provides enhanced support for editing MSBuild files in Visual Studio. It includes IntelliSense, Quick Info, navigation, validation, code fixes, and refactorings, all driven by a powerful and customizable schema-based type system.
 
-You can install the extension from [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mhutch.msbuildeditor), download a [CI build](https://github.com/mhutch/MonoDevelop.MSBuildEditor/actions), or build from source.
+You can install the extension from the Visual Studio Extension Manager or from the [Visual Studio Marketplace](https://marketplace.visualstudio.com/items?itemName=mhutch.msbuildeditor), download a [CI build](https://github.com/mhutch/MonoDevelop.MSBuildEditor/actions), or build from source.
 <br><br>
 
 **⚠️ The editor is currently in preview.<br>
 📝 Please report bugs and feature requests in the GitHub repo.<br>
 🎉 Pull requests are also much appreciated!**
+<br>
+
+**Please let us know about your experience by filling out [this survey](https://www.surveymonkey.com/r/G3F9SC3)**.
 <br><br>
 
+We appreciate your feedback, and it will help guide how the experiment develops and whether the MSBuild Editor becomes an officially supported part of the .NET development experience.
+
+*For an explanation of why the repo and assembly names contains "MonoDevelop", see [this discussion post](https://github.com/mhutch/MonoDevelop.MSBuildEditor/discussions/197#discussioncomment-9098580).*
+
+
 ## Development
 
 Bugs and proposed features are tracked in [GitHub issues](issues), though some older items have not yet been migrated from the [TODO](TODO.md). If you're interested in implementing a feature or fixing a bug and have any questions at all, please cc @mhutch on a comment on the appropriate new or existing GitHub issue.
@@ -68,6 +76,8 @@ In addition to the schema inferred from the items, metadata, properties and task
 
 Any targets file can provide a schema 'sidecar', which has the same name as the targets file except with the suffix `.buildschema.json`. The editor will load the sidecar schemas for any targets that it imports. This allows MSBuild targets to provide their own documentation.
 
+The wiki contains [guidance on creating custom schemas](https://github.com/mhutch/MonoDevelop.MSBuildEditor/wiki/Creating-a-custom-schema) and documents the [schema format](https://github.com/mhutch/MonoDevelop.MSBuildEditor/wiki/Schema-structure).
+
 ![](images/vs-schema.png)
 
 The extension includes built-in schemas for `Microsoft.Common.targets`, `Microsoft.NET.Sdk`, and other common targets and MSBuild SDKs.