From e4f3d274f5834c14c9178e04b8532e8c344749e5 Mon Sep 17 00:00:00 2001 From: Andre Weinand Date: Tue, 23 Nov 2021 14:30:56 +0100 Subject: [PATCH] add new category 'important' to the 'output' event; fixes #218 --- _data/specification-toc.yml | 17 +---------------- changelog.md | 3 +++ debugAdapterProtocol.json | 11 +++++++++-- specification.md | 35 +++++++++++++++++++++++++---------- 4 files changed, 38 insertions(+), 28 deletions(-) diff --git a/_data/specification-toc.yml b/_data/specification-toc.yml index c8ba416..8b8436e 100644 --- a/_data/specification-toc.yml +++ b/_data/specification-toc.yml @@ -1,20 +1,5 @@ -- title: Debug Adapter Protocol +- title: Base Protocol children: - - title: Base Protocol - anchor: Base_Protocol - children: - - title: Cancel - anchor: Base_Protocol_Cancel - - title: ErrorResponse - anchor: Base_Protocol_ErrorResponse - - title: Event - anchor: Base_Protocol_Event - - title: ProtocolMessage - anchor: Base_Protocol_ProtocolMessage - - title: Request - anchor: Base_Protocol_Request - - title: Response - anchor: Base_Protocol_Response - title: Events anchor: Events children: diff --git a/changelog.md b/changelog.md index 5310cdf..02f280a 100644 --- a/changelog.md +++ b/changelog.md @@ -6,6 +6,9 @@ sectionid: changelog #### All notable changes to the specification will be documented in this file. +* 1.50.x: + * Add a new category `important` to the `output` event. This is a hint for clients to show the message with a highly visible UI. + * 1.49.x: * Add `memory` event and a corresponding **client** capability `supportsMemoryEvent`. diff --git a/debugAdapterProtocol.json b/debugAdapterProtocol.json index d2ea49f..1ab12e9 100644 --- a/debugAdapterProtocol.json +++ b/debugAdapterProtocol.json @@ -348,8 +348,15 @@ "properties": { "category": { "type": "string", - "description": "The output category. If not specified, 'console' is assumed.", - "_enum": [ "console", "stdout", "stderr", "telemetry" ] + "description": "The output category. If not specified or if the category is not understand by the client, 'console' is assumed.", + "_enum": [ "console", "important", "stdout", "stderr", "telemetry" ], + "enumDescriptions": [ + "Show the output in the client's default message UI, e.g. a 'debug console'. This category should only be used for informational output from the debugger (as opposed to the debuggee).", + "A hint for the client to show the ouput in the client's UI for important and highly visible information, e.g. as a popup notification. This category should only be used for important messages from the debugger (as opposed to the debuggee). Since this category value is a hint, clients might ignore the hint and assume the 'console' category.", + "Show the output as normal program output from the debuggee.", + "Show the output as error program output from the debuggee.", + "Send the output to telemetry instead of showing it to the user." + ] }, "output": { "type": "string", diff --git a/specification.md b/specification.md index 5a23f55..f43b1db 100644 --- a/specification.md +++ b/specification.md @@ -14,9 +14,9 @@ A machine-readable JSON schema can be found [here](./debugAdapterProtocol.json). The change history of the specification lives [here](./changelog). -## Base Protocol +## Base Protocol -### ProtocolMessage +### ProtocolMessage Base class of requests, responses, and events. @@ -36,7 +36,7 @@ interface ProtocolMessage { } ``` -### Request +### Request A client or debug adapter initiated request. @@ -56,7 +56,7 @@ interface Request extends ProtocolMessage { } ``` -### Event +### Event A debug adapter initiated event. @@ -76,7 +76,7 @@ interface Event extends ProtocolMessage { } ``` -### Response +### Response Response for a request. @@ -123,7 +123,7 @@ interface Response extends ProtocolMessage { } ``` -### ErrorResponse +### ErrorResponse On error (whenever 'success' is false), the body can provide more details. @@ -138,7 +138,7 @@ interface ErrorResponse extends Response { } ``` -### :leftwards_arrow_with_hook: Cancel Request +### :leftwards_arrow_with_hook: Cancel Request The 'cancel' request is used by the frontend in two situations: - to indicate that it is no longer interested in the result produced by a specific request issued earlier @@ -386,10 +386,25 @@ interface OutputEvent extends Event { body: { /** - * The output category. If not specified, 'console' is assumed. - * Values: 'console', 'stdout', 'stderr', 'telemetry', etc. + * The output category. If not specified or if the category is not + * understand by the client, 'console' is assumed. + * Values: + * 'console': Show the output in the client's default message UI, e.g. a + * 'debug console'. This category should only be used for informational + * output from the debugger (as opposed to the debuggee). + * 'important': A hint for the client to show the ouput in the client's UI + * for important and highly visible information, e.g. as a popup + * notification. This category should only be used for important messages + * from the debugger (as opposed to the debuggee). Since this category value + * is a hint, clients might ignore the hint and assume the 'console' + * category. + * 'stdout': Show the output as normal program output from the debuggee. + * 'stderr': Show the output as error program output from the debuggee. + * 'telemetry': Send the output to telemetry instead of showing it to the + * user. + * etc. */ - category?: 'console' | 'stdout' | 'stderr' | 'telemetry' | string; + category?: 'console' | 'important' | 'stdout' | 'stderr' | 'telemetry' | string; /** * The output to report.