From 0feca9b494cfa80451895c4e105cdab72d901dfb Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Thu, 18 Jul 2024 10:21:18 -0700 Subject: [PATCH 1/3] Add TypeSpec Definition for APIView TreeStyle Parser --- .../json-schema/APITreeNode.json | 90 +++++++++++ .../json-schema/APITreeNodeProperties.json | 11 ++ .../json-schema/APITreeNodeTags.json | 31 ++++ .../json-schema/CodeDiagnostic.json | 30 ++++ .../json-schema/CodeDiagnosticLevel.json | 12 ++ .../json-schema/StructuredToken.json | 41 +++++ .../json-schema/StructuredTokenKind.json | 12 ++ .../StructuredTokenProperties.json | 16 ++ .../StructuredTokenRenderClasses.json | 50 ++++++ .../json-schema/StructuredTokenTags.json | 16 ++ .../models.tsp | 150 ++++++++++++++++++ 11 files changed, 459 insertions(+) create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json new file mode 100644 index 00000000000..2d3d2a9a47a --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json @@ -0,0 +1,90 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNode.json", + "type": "object", + "properties": { + "Name": { + "type": "string", + "description": "The name of the tree node which will be used as label for the API Navigation. Generally this is the name of the module (class, method)." + }, + "Id": { + "type": "string", + "description": "Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node." + }, + "Kind": { + "anyOf": [ + { + "type": "string", + "const": "assembly" + }, + { + "type": "string", + "const": "namespace" + }, + { + "type": "string", + "const": "class" + }, + { + "type": "string", + "const": "delegate" + }, + { + "type": "string", + "const": "enum" + }, + { + "type": "string", + "const": "interface" + }, + { + "type": "string", + "const": "method" + }, + { + "type": "string", + "const": "package" + }, + { + "type": "string", + "const": "struct" + }, + { + "type": "string", + "const": "type" + } + ], + "description": "The kind of node" + }, + "BottomTokens": { + "type": "array", + "items": { + "$ref": "StructuredToken.json" + }, + "description": "Tokens which are rendered after all child nodes. Depending on the language this would include the closing curly brace and/or empty lines." + }, + "Children": { + "type": "array", + "items": { + "$ref": "APITreeNode.json" + }, + "description": "The nodes immediate children. For a namespace this would be classes, for a class this would be the class constructors and methods. Children are rendered after TopTokens but before BottomTokens, and are automatically indented." + }, + "Properties": { + "$ref": "APITreeNodeProperties.json", + "description": "Properties of the APITreeNode." + }, + "Tags": { + "type": "array", + "items": { + "$ref": "APITreeNodeTags.json" + }, + "description": "Tags of the APITreeNode." + } + }, + "required": [ + "Name", + "Id", + "Kind" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json new file mode 100644 index 00000000000..dddef5f64c9 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json @@ -0,0 +1,11 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNodeProperties.json", + "type": "object", + "properties": { + "IconName": { + "type": "string", + "description": "Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind" + } + } +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json new file mode 100644 index 00000000000..ee874511c03 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json @@ -0,0 +1,31 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNodeTags.json", + "anyOf": [ + { + "type": "string", + "const": "Deprecated", + "description": "Mark a token as deprecated." + }, + { + "type": "string", + "const": "Hidden", + "description": "Mark a node as Hidden." + }, + { + "type": "string", + "const": "HideFromNav", + "description": "Indicate that a node should be hidden from the page navigation." + }, + { + "type": "string", + "const": "SkipDiff", + "description": "Indicate that a node should not be used in computation of diff." + }, + { + "type": "string", + "const": "CrossLangDefId", + "description": "The cross language definitionId for the node." + } + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json new file mode 100644 index 00000000000..a91c6e29973 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json @@ -0,0 +1,30 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "CodeDiagnostic.json", + "type": "object", + "properties": { + "DiagnosticId": { + "type": "string" + }, + "Text": { + "type": "string" + }, + "HelpLinkUri": { + "type": "string" + }, + "TargetId": { + "type": "string", + "description": "Maps to the APITreeNode id" + }, + "Level": { + "$ref": "CodeDiagnosticLevel.json" + } + }, + "required": [ + "DiagnosticId", + "Text", + "HelpLinkUri", + "TargetId", + "Level" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json new file mode 100644 index 00000000000..6e6381705e4 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "CodeDiagnosticLevel.json", + "type": "string", + "enum": [ + "Default", + "Info", + "Warning", + "Error", + "Fatal" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json new file mode 100644 index 00000000000..78847620a5d --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredToken.json", + "type": "object", + "properties": { + "Id": { + "type": "string", + "description": "Token Id. Previously known as DefinitionId." + }, + "Kind": { + "$ref": "StructuredTokenKind.json", + "description": "Represents the type of a structured token" + }, + "Value": { + "type": "string", + "description": "The token value which will be displayed. Spacing tokens (LineBreak, NonBreakingSpace, TabSpace, and ParameterSeparator) don't need to have value" + }, + "Properties": { + "$ref": "StructuredTokenProperties.json", + "description": "Properties of the StructuredToken." + }, + "Tags": { + "type": "array", + "items": { + "$ref": "StructuredTokenTags.json" + }, + "description": "Tags of the StructuredToken." + }, + "RenderClasses": { + "type": "array", + "items": { + "$ref": "StructuredTokenRenderClasses.json" + }, + "description": "Classes used to render the StructuredTokens." + } + }, + "required": [ + "Id", + "Kind" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json new file mode 100644 index 00000000000..356125111ba --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json @@ -0,0 +1,12 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenKind.json", + "type": "string", + "enum": [ + "Content", + "LineBreak", + "NonBreakingSpace", + "TabSpace", + "ParameterSeparator" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json new file mode 100644 index 00000000000..b2b4d32f532 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenProperties.json", + "type": "object", + "properties": { + "GroupId": { + "type": "string", + "const": "doc", + "description": "Group a sequence of consecutive StructuredTokens. doc indicates that the group of tokens is documentation." + }, + "NavigateToId": { + "type": "string", + "description": "Id to navigate to when StructuredToken is clicked." + } + } +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json new file mode 100644 index 00000000000..cb6d222231d --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json @@ -0,0 +1,50 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenRenderClasses.json", + "anyOf": [ + { + "type": "string", + "const": "comment" + }, + { + "type": "string", + "const": "keyword" + }, + { + "type": "string", + "const": "keyword" + }, + { + "type": "string", + "const": "literal" + }, + { + "type": "string", + "const": "sliteral", + "description": "string literal" + }, + { + "type": "string", + "const": "mname", + "description": "member name" + }, + { + "type": "string", + "const": "tname", + "description": "type name" + }, + { + "type": "string", + "const": "punc", + "description": "punctuation" + }, + { + "type": "string", + "const": "text" + }, + { + "type": "string" + } + ], + "description": "Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss" +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json new file mode 100644 index 00000000000..088027e1108 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json @@ -0,0 +1,16 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenTags.json", + "anyOf": [ + { + "type": "string", + "const": "Deprecated", + "description": "Mark a token as deprecated" + }, + { + "type": "string", + "const": "SkipDiff", + "description": "Indicate that a Token should not be used in computing diff" + } + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp new file mode 100644 index 00000000000..df683a8927e --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp @@ -0,0 +1,150 @@ +model CodeFile { + /** The version of the parser */ + VersionString: string; + + /** Name the ocde file. Usually just the package name and version*/ + Name: string; + + Language: string; + LanguageVariant: "Default" | "Spring" | "Android"; + PackageName: string; + ServiceName: string; + PackageVersion: string; + + /** Maps related packages across Languages */ + CrossLanguagePackageId: string; + + /** The API Tree(s) */ + APIForest: APITreeNode[]; + + Diagnostics: CodeDiagnostic[]; +} + +model CodeDiagnostic { + DiagnosticId: string; + Text: string; + HelpLinkUri: string; + + /** Maps to the APITreeNode id */ + TargetId: string; + Level: CodeDiagnosticLevel; +} + +model APITreeNode { + /** The name of the tree node which will be used as label for the API Navigation. Generally this is the name of the module (class, method). */ + Name: string; + + /** Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node. */ + Id: string; + + /** The kind of node */ + Kind: "assembly" | "namespace" | "class" | "delegate" | "enum" | "interface" | "method" | "package" | "struct" | "type"; + + /** Tokens which are rendered after all child nodes. Depending on the language this would include the closing curly brace and/or empty lines. */ + BottomTokens?: StructuredToken[]; + + /** The nodes immediate children. For a namespace this would be classes, for a class this would be the class constructors and methods. Children are rendered after TopTokens but before BottomTokens, and are automatically indented.*/ + Children?: APITreeNode[]; + + /** Properties of the APITreeNode. */ + Properties?: APITreeNodeProperties; + + /** Tags of the APITreeNode. */ + Tags?: APITreeNodeTags[]; +} + +model StructuredToken { + /** Token Id. Previously known as DefinitionId. */ + Id: string; + + /** Represents the type of a structured token*/ + Kind: StructuredTokenKind; + + /** The token value which will be displayed. Spacing tokens (LineBreak, NonBreakingSpace, TabSpace, and ParameterSeparator) don't need to have value */ + Value?: string; + + /** Properties of the StructuredToken. */ + Properties?: StructuredTokenProperties; + + /** Tags of the StructuredToken. */ + Tags?: StructuredTokenTags[]; + + /** Classes used to render the StructuredTokens. */ + RenderClasses?: StructuredTokenRenderClasses[] +} + +model APITreeNodeProperties { + /** Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind*/ + IconName?: string; +} + +model StructuredTokenProperties { + /** Group a sequence of consecutive StructuredTokens. doc indicates that the group of tokens is documentation. */ + GroupId?: "doc"; + + /** Id to navigate to when StructuredToken is clicked. */ + NavigateToId?: string; +} + +enum StructuredTokenKind { + /** Default kind */ + Content, + + /** Starts a new line */ + LineBreak, + + /** Single Space */ + NonBreakingSpace, + + /** Four spaces */ + TabSpace, + + /** Use this between method parameters. Depending on user setting this would result in a LineBreak or a LineBreak + TabSpace */ + ParameterSeparator +} + +/** Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss */ +union StructuredTokenRenderClasses { + "comment", + "keyword", + "keyword", + "literal", + /** string literal */ + "sliteral", + /** member name */ + "mname", + /** type name */ + "tname", + /** punctuation */ + "punc", + "text", + string +} + +union APITreeNodeTags { + /** Mark a token as deprecated. */ + "Deprecated", + /** Mark a node as Hidden. */ + "Hidden", + /** Indicate that a node should be hidden from the page navigation. */ + "HideFromNav", + /** Indicate that a node should not be used in computation of diff. */ + "SkipDiff", + /** The cross language definitionId for the node. */ + "CrossLangDefId" +} + +union StructuredTokenTags { + /** Mark a token as deprecated */ + "Deprecated", + /** Indicate that a Token should not be used in computing diff*/ + "SkipDiff", +} + +enum CodeDiagnosticLevel { + Default, + Info, + Warning, + Error, + Fatal +} \ No newline at end of file From f4f25a1ef499622cf83db16113b60e6f1a6c2f71 Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Mon, 22 Jul 2024 11:04:34 -0700 Subject: [PATCH 2/3] Update TreeStyleParser Schema --- .../json-schema/APITreeNode.json | 11 +- .../json-schema/APITreeNodeId.json | 5 + .../json-schema/APITreeNodeProperties.json | 4 + .../json-schema/APITreeNodeTags.json | 5 - .../json-schema/CodeDiagnostic.json | 5 +- .../json-schema/CodeDiagnosticLevel.json | 11 +- .../json-schema/CodeFile.json | 123 ++++++++++++++ .../json-schema/StructuredToken.json | 2 +- .../json-schema/StructuredTokenId.json | 5 + .../json-schema/StructuredTokenKind.json | 12 +- .../StructuredTokenProperties.json | 2 +- .../StructuredTokenRenderClasses.json | 7 +- .../models.tsp | 151 +++++++++--------- 13 files changed, 242 insertions(+), 101 deletions(-) create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json create mode 100644 tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json index 2d3d2a9a47a..6bcf42a4488 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json @@ -8,7 +8,7 @@ "description": "The name of the tree node which will be used as label for the API Navigation. Generally this is the name of the module (class, method)." }, "Id": { - "type": "string", + "$ref": "APITreeNodeId.json", "description": "Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node." }, "Kind": { @@ -54,7 +54,14 @@ "const": "type" } ], - "description": "The kind of node" + "description": "Descriptor for the kind of the node. Currently used to select navigation icons" + }, + "TopTokens": { + "type": "array", + "items": { + "$ref": "StructuredToken.json" + }, + "description": "The main data of the node. This is all the tokens that actually define the node. When rendering, TopTokens are rendered first, followed by any Children, and then finally BottomTokens" }, "BottomTokens": { "type": "array", diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json new file mode 100644 index 00000000000..308fcbc047e --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "APITreeNodeId.json", + "type": "string" +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json index dddef5f64c9..d71e1ac374a 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json @@ -6,6 +6,10 @@ "IconName": { "type": "string", "description": "Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind" + }, + "CrossLangDefId": { + "type": "string", + "description": "The cross language definitionId for the node." } } } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json index ee874511c03..0d2911beafb 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json @@ -21,11 +21,6 @@ "type": "string", "const": "SkipDiff", "description": "Indicate that a node should not be used in computation of diff." - }, - { - "type": "string", - "const": "CrossLangDefId", - "description": "The cross language definitionId for the node." } ] } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json index a91c6e29973..9723e72d536 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json @@ -4,7 +4,8 @@ "type": "object", "properties": { "DiagnosticId": { - "type": "string" + "type": "string", + "description": "String associated with a given diagnostic usieally produced by an analyzer" }, "Text": { "type": "string" @@ -13,7 +14,7 @@ "type": "string" }, "TargetId": { - "type": "string", + "$ref": "APITreeNodeId.json", "description": "Maps to the APITreeNode id" }, "Level": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json index 6e6381705e4..2a1943b50cf 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json @@ -1,12 +1,11 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "CodeDiagnosticLevel.json", - "type": "string", + "type": "number", "enum": [ - "Default", - "Info", - "Warning", - "Error", - "Fatal" + 1, + 2, + 3, + 4 ] } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json new file mode 100644 index 00000000000..d1d2d424db6 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json @@ -0,0 +1,123 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "CodeFile.json", + "type": "object", + "properties": { + "VersionString": { + "type": "string", + "description": "The version of the parser" + }, + "Name": { + "type": "string", + "description": "Name the ocde file. Usually just the package name and version" + }, + "Language": { + "anyOf": [ + { + "type": "string", + "const": "C" + }, + { + "type": "string", + "const": "C#" + }, + { + "type": "string", + "const": "C++" + }, + { + "type": "string", + "const": "Go" + }, + { + "type": "string", + "const": "Java" + }, + { + "type": "string", + "const": "JavaScript" + }, + { + "type": "string", + "const": "Json" + }, + { + "type": "string", + "const": "Kotlin" + }, + { + "type": "string", + "const": "Python" + }, + { + "type": "string", + "const": "Swagger" + }, + { + "type": "string", + "const": "Swift" + }, + { + "type": "string", + "const": "TypeSpec" + }, + { + "type": "string", + "const": "Xml" + } + ] + }, + "LanguageVariant": { + "anyOf": [ + { + "type": "string", + "const": "Default" + }, + { + "type": "string", + "const": "Spring" + }, + { + "type": "string", + "const": "Android" + } + ], + "default": "Default" + }, + "PackageName": { + "type": "string" + }, + "ServiceName": { + "type": "string" + }, + "PackageVersion": { + "type": "string" + }, + "CrossLanguagePackageId": { + "type": "string", + "description": "Maps related packages across Languages" + }, + "APIForest": { + "type": "array", + "items": { + "$ref": "APITreeNode.json" + }, + "description": "The API Tree(s)" + }, + "Diagnostics": { + "type": "array", + "items": { + "$ref": "CodeDiagnostic.json" + } + } + }, + "required": [ + "VersionString", + "Name", + "Language", + "PackageName", + "PackageVersion", + "APIForest", + "Diagnostics" + ] +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json index 78847620a5d..d87d44cee04 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json @@ -4,7 +4,7 @@ "type": "object", "properties": { "Id": { - "type": "string", + "$ref": "StructuredTokenId.json", "description": "Token Id. Previously known as DefinitionId." }, "Kind": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json new file mode 100644 index 00000000000..3792a7c7058 --- /dev/null +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json @@ -0,0 +1,5 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "StructuredTokenId.json", + "type": "string" +} \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json index 356125111ba..a31d1e4060e 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json @@ -1,12 +1,12 @@ { "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "StructuredTokenKind.json", - "type": "string", + "type": "number", "enum": [ - "Content", - "LineBreak", - "NonBreakingSpace", - "TabSpace", - "ParameterSeparator" + 0, + 1, + 2, + 3, + 4 ] } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json index b2b4d32f532..2588e994465 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json @@ -9,7 +9,7 @@ "description": "Group a sequence of consecutive StructuredTokens. doc indicates that the group of tokens is documentation." }, "NavigateToId": { - "type": "string", + "$ref": "APITreeNodeId.json", "description": "Id to navigate to when StructuredToken is clicked." } } diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json index cb6d222231d..e7856edce2a 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json @@ -10,10 +10,6 @@ "type": "string", "const": "keyword" }, - { - "type": "string", - "const": "keyword" - }, { "type": "string", "const": "literal" @@ -43,7 +39,8 @@ "const": "text" }, { - "type": "string" + "type": "string", + "description": "Contribute extra classes at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss" } ], "description": "Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss" diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp index df683a8927e..a23d58ce894 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp @@ -1,3 +1,66 @@ +scalar StructuredTokenId extends string; +scalar APITreeNodeId extends string; + +enum StructuredTokenKind { + /** Default kind */ + Content: 0, + + /** Starts a new line */ + LineBreak: 1, + + /** Single Space */ + NonBreakingSpace: 2, + + /** Four spaces */ + TabSpace: 3, + + /** Use this between method parameters. Depending on user setting this would result in a LineBreak or a LineBreak + TabSpace */ + ParameterSeparator: 4 +} + +enum CodeDiagnosticLevel { + Info: 1, + Warning: 2, + Error: 3, + Fatal: 4 +} + +/** Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss */ +union StructuredTokenRenderClasses { + "comment", + "keyword", + "literal", + /** string literal */ + "sliteral", + /** member name */ + "mname", + /** type name */ + "tname", + /** punctuation */ + "punc", + "text", + /** Contribute extra classes at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss */ + string +} + +union APITreeNodeTags { + /** Mark a token as deprecated. */ + "Deprecated", + /** Mark a node as Hidden. */ + "Hidden", + /** Indicate that a node should be hidden from the page navigation. */ + "HideFromNav", + /** Indicate that a node should not be used in computation of diff. */ + "SkipDiff" +} + +union StructuredTokenTags { + /** Mark a token as deprecated */ + "Deprecated", + /** Indicate that a Token should not be used in computing diff*/ + "SkipDiff", +} + model CodeFile { /** The version of the parser */ VersionString: string; @@ -5,14 +68,14 @@ model CodeFile { /** Name the ocde file. Usually just the package name and version*/ Name: string; - Language: string; - LanguageVariant: "Default" | "Spring" | "Android"; + Language: "C" | "C#"| "C++" | "Go" | "Java" | "JavaScript" | "Json" | "Kotlin" | "Python" | "Swagger" | "Swift" | "TypeSpec" | "Xml"; + LanguageVariant?: "Default" | "Spring" | "Android" = "Default"; PackageName: string; - ServiceName: string; + ServiceName?: string; PackageVersion: string; /** Maps related packages across Languages */ - CrossLanguagePackageId: string; + CrossLanguagePackageId?: string; /** The API Tree(s) */ APIForest: APITreeNode[]; @@ -21,12 +84,12 @@ model CodeFile { } model CodeDiagnostic { + /** String associated with a given diagnostic usieally produced by an analyzer*/ DiagnosticId: string; Text: string; HelpLinkUri: string; - /** Maps to the APITreeNode id */ - TargetId: string; + TargetId: APITreeNodeId; Level: CodeDiagnosticLevel; } @@ -35,11 +98,14 @@ model APITreeNode { Name: string; /** Id of the node, which should be unique at the node level. i.e. unique among its siblings. This was previously represented by the DefinitionId for the main Token of the node. */ - Id: string; + Id: APITreeNodeId; - /** The kind of node */ + /** Descriptor for the kind of the node. Currently used to select navigation icons */ Kind: "assembly" | "namespace" | "class" | "delegate" | "enum" | "interface" | "method" | "package" | "struct" | "type"; + /** The main data of the node. This is all the tokens that actually define the node. When rendering, TopTokens are rendered first, followed by any Children, and then finally BottomTokens */ + TopTokens?: StructuredToken[]; + /** Tokens which are rendered after all child nodes. Depending on the language this would include the closing curly brace and/or empty lines. */ BottomTokens?: StructuredToken[]; @@ -55,7 +121,7 @@ model APITreeNode { model StructuredToken { /** Token Id. Previously known as DefinitionId. */ - Id: string; + Id: StructuredTokenId; /** Represents the type of a structured token*/ Kind: StructuredTokenKind; @@ -76,6 +142,8 @@ model StructuredToken { model APITreeNodeProperties { /** Use this only if you are looking to add a custom icon different from language wide defaults set by APITreeNode kind*/ IconName?: string; + /** The cross language definitionId for the node. */ + CrossLangDefId?: string; } model StructuredTokenProperties { @@ -83,68 +151,5 @@ model StructuredTokenProperties { GroupId?: "doc"; /** Id to navigate to when StructuredToken is clicked. */ - NavigateToId?: string; -} - -enum StructuredTokenKind { - /** Default kind */ - Content, - - /** Starts a new line */ - LineBreak, - - /** Single Space */ - NonBreakingSpace, - - /** Four spaces */ - TabSpace, - - /** Use this between method parameters. Depending on user setting this would result in a LineBreak or a LineBreak + TabSpace */ - ParameterSeparator -} - -/** Classes used to render the StructuredTokens. Extendable by contributing styles at https://github.com/Azure/azure-sdk-tools/blob/main/src/dotnet/APIView/ClientSPA/src/app/_components/code-panel/code-panel.component.scss */ -union StructuredTokenRenderClasses { - "comment", - "keyword", - "keyword", - "literal", - /** string literal */ - "sliteral", - /** member name */ - "mname", - /** type name */ - "tname", - /** punctuation */ - "punc", - "text", - string -} - -union APITreeNodeTags { - /** Mark a token as deprecated. */ - "Deprecated", - /** Mark a node as Hidden. */ - "Hidden", - /** Indicate that a node should be hidden from the page navigation. */ - "HideFromNav", - /** Indicate that a node should not be used in computation of diff. */ - "SkipDiff", - /** The cross language definitionId for the node. */ - "CrossLangDefId" -} - -union StructuredTokenTags { - /** Mark a token as deprecated */ - "Deprecated", - /** Indicate that a Token should not be used in computing diff*/ - "SkipDiff", -} - -enum CodeDiagnosticLevel { - Default, - Info, - Warning, - Error, - Fatal + NavigateToId?: APITreeNodeId; } \ No newline at end of file From f5d1de7601e27a2c9bfac54dc6902104efb739f2 Mon Sep 17 00:00:00 2001 From: Chidozie Ononiwu Date: Wed, 24 Jul 2024 15:34:12 -0700 Subject: [PATCH 3/3] Update StructuredToken id documentation, and update json schema --- .../json-schema/APITreeNode.json | 2 +- .../json-schema/APITreeNodeId.json | 2 +- .../json-schema/APITreeNodeProperties.json | 2 +- .../json-schema/APITreeNodeTags.json | 2 +- .../json-schema/CodeDiagnostic.json | 2 +- .../json-schema/CodeDiagnosticLevel.json | 2 +- .../apiview-treestyle-parser-schema/json-schema/CodeFile.json | 2 +- .../json-schema/StructuredToken.json | 4 ++-- .../json-schema/StructuredTokenId.json | 2 +- .../json-schema/StructuredTokenKind.json | 2 +- .../json-schema/StructuredTokenProperties.json | 2 +- .../json-schema/StructuredTokenRenderClasses.json | 2 +- .../json-schema/StructuredTokenTags.json | 2 +- .../parsers/apiview-treestyle-parser-schema/models.tsp | 2 +- 14 files changed, 15 insertions(+), 15 deletions(-) diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json index 6bcf42a4488..1a26a0410f0 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNode.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "APITreeNode.json", "type": "object", "properties": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json index 308fcbc047e..8bbd3dc0156 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeId.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "APITreeNodeId.json", "type": "string" } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json index d71e1ac374a..4e66c5e2f75 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeProperties.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "APITreeNodeProperties.json", "type": "object", "properties": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json index 0d2911beafb..71eadfe22a6 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/APITreeNodeTags.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "APITreeNodeTags.json", "anyOf": [ { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json index 9723e72d536..b500b2c3b21 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnostic.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "CodeDiagnostic.json", "type": "object", "properties": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json index 2a1943b50cf..92cf68b5b51 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeDiagnosticLevel.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "CodeDiagnosticLevel.json", "type": "number", "enum": [ diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json index d1d2d424db6..0ba9b2d2741 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/CodeFile.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "CodeFile.json", "type": "object", "properties": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json index d87d44cee04..e834ea66c92 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredToken.json @@ -1,11 +1,11 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredToken.json", "type": "object", "properties": { "Id": { "$ref": "StructuredTokenId.json", - "description": "Token Id. Previously known as DefinitionId." + "description": "Token Id. Previously known as DefinitionId. Also the id used to place APIView comments. Needs to be deterministic" }, "Kind": { "$ref": "StructuredTokenKind.json", diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json index 3792a7c7058..32ed4942049 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenId.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredTokenId.json", "type": "string" } \ No newline at end of file diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json index a31d1e4060e..5481a0d6472 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenKind.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredTokenKind.json", "type": "number", "enum": [ diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json index 2588e994465..539979162a9 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenProperties.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredTokenProperties.json", "type": "object", "properties": { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json index e7856edce2a..8c84e034002 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenRenderClasses.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredTokenRenderClasses.json", "anyOf": [ { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json index 088027e1108..3534f2bc6e4 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/json-schema/StructuredTokenTags.json @@ -1,5 +1,5 @@ { - "$schema": "https://json-schema.org/draft/2020-12/schema", + "$schema": "http://json-schema.org/draft-07/schema#", "$id": "StructuredTokenTags.json", "anyOf": [ { diff --git a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp index a23d58ce894..187b900145c 100644 --- a/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp +++ b/tools/apiview/parsers/apiview-treestyle-parser-schema/models.tsp @@ -120,7 +120,7 @@ model APITreeNode { } model StructuredToken { - /** Token Id. Previously known as DefinitionId. */ + /** Token Id. Previously known as DefinitionId. Also the id used to place APIView comments. Needs to be deterministic */ Id: StructuredTokenId; /** Represents the type of a structured token*/