Better comments, clearer intention with code/name

Author: Clayton Pence

analysis/v1alpha1/message.gen.json

@@ -9,6 +9,23 @@
       "istio.analysis.v1alpha1.AnalysisMessageBase": {
         "description": "AnalysisMessageBase describes some common information that is needed for all messages. All information should be static with respect to the error code.",
         "type": "object",
+        "properties": {
+          "type": {
+            "$ref": "#/components/schemas/istio.analysis.v1alpha1.AnalysisMessageBase.Type"
+          },
+          "level": {
+            "$ref": "#/components/schemas/istio.analysis.v1alpha1.AnalysisMessageBase.Level"
+          },
+          "documentationUrl": {
+            "description": "A url pointing to the Istio documentation for this specific error type. Should be of the form `^http(s)?://(preliminary\\.)?istio.io/docs/reference/config/analysis/` Required.",
+            "type": "string",
+            "format": "string"
+          }
+        }
+      },
+      "istio.analysis.v1alpha1.AnalysisMessageBase.Type": {
+        "description": "A unique identifier for the type of message. Name is intended to be human-readable, code is intended to be machine readable. There should be a one-to-one mapping between name and code. (i.e. do not re-use names or codes between message types.)",
+        "type": "object",
         "properties": {
           "name": {
             "description": "A human-readable name for the message type. e.g. \"InternalError\", \"PodMissingProxy\". This should be the same for all messages of the same type. Required.",
@@ -19,14 +36,6 @@
             "description": "A 7 character code matching `^IST[0-9]{4}$` intended to uniquely identify the message type. (e.g. \"IST0001\" is mapped to the \"InternalError\" message type.) 0000-0100 are reserved. Required.",
             "type": "string",
             "format": "string"
-          },
-          "level": {
-            "$ref": "#/components/schemas/istio.analysis.v1alpha1.AnalysisMessageBase.Level"
-          },
-          "documentationUrl": {
-            "description": "A url pointing to the Istio documentation for this specific error type. Should be of the form `^http(s)?://(preliminary\\.)?istio.io/docs/reference/config/analysis/` Required.",
-            "type": "string",
-            "format": "string"
           }
         }
       },
@@ -53,7 +62,7 @@
             "format": "string"
           },
           "template": {
-            "description": "A go-style template string defining how to combine the args for a particular message into a log line. Required.",
+            "description": "A go-style template string (https://golang.org/pkg/fmt/#hdr-Printing) defining how to combine the args for a particular message into a log line. Required.",
             "type": "string",
             "format": "string"
           },
@@ -75,7 +84,7 @@
             "format": "string"
           },
           "goType": {
-            "description": "Required. Should be a golang type, used in code generation",
+            "description": "Required. Should be a golang type, used in code generation. Ideally this will change to a less language-pinned type before this gets out of alpha, but for compatibility with current istio/istio code it's go_type for now.",
             "type": "string",
             "format": "string"
           }
@@ -93,7 +102,7 @@
             "type": "object"
           },
           "resourcePaths": {
-            "description": "A list of strings specifying the path for resources which were the cause of message generation. At least one is required.",
+            "description": "A list of strings specifying the resource identifiers that were the cause of message generation. At least one is required.",
             "type": "array",
             "items": {
               "type": "string",