ruby-dap 0.1.2 → 0.1.3

data/lib/dap/modules_arguments.rb

@@ -1,7 +1,8 @@
+# Arguments for ‘modules’ request.
 class DAP::ModulesArguments < DAP::Base
   # The index of the first module to return; if omitted modules start at 0.
-  property :startModule, required: false
+  property :startModule, required: false, as: 'number'
 
   # The number of modules to return. If moduleCount is not specified or 0, all modules are returned.
-  property :moduleCount, required: false
+  property :moduleCount, required: false, as: 'number'
 end

data/lib/dap/modules_response_body.rb

@@ -1,9 +1,10 @@
 require_relative 'module'
 
+# Response to ‘modules’ request.
 class DAP::ModulesResponseBody < DAP::Base
   # All modules or range of modules.
   property :modules, as: many(DAP::Module)
 
   # The total number of modules available.
-  property :totalModules, required: false
+  property :totalModules, required: false, as: 'number'
 end

data/lib/dap/next_arguments.rb

@@ -1,8 +1,9 @@
 require_relative 'stepping_granularity'
 
+# Arguments for ‘next’ request.
 class DAP::NextArguments < DAP::Base
   # Execute 'next' for this thread.
-  property :threadId
+  property :threadId, as: 'number'
 
   # Optional granularity to step. If no granularity is specified, a granularity of 'statement' is assumed.
   property :granularity, required: false, as: DAP::SteppingGranularity

data/lib/dap/output_event_body.rb

@@ -1,12 +1,13 @@
 require_relative 'source'
 
+# The event indicates that the target has produced some output.
 class DAP::OutputEventBody < DAP::Base
   # The output category. If not specified, 'console' is assumed.
   # Values: 'console', 'stdout', 'stderr', 'telemetry', etc.
-  property :category, required: false # 'console' | 'stdout' | 'stderr' | 'telemetry' | string
+  property :category, required: false, as: 'string'
 
   # The output to report.
-  property :output
+  property :output, as: 'string'
 
   # Support for keeping an output log organized by grouping related messages.
   # Values:
@@ -17,19 +18,19 @@ class DAP::OutputEventBody < DAP::Base
   # 'end': End the current group and decreases the indentation of subsequent output events.
   # A non empty 'output' attribute is shown as the unindented end of the group.
   # etc.
-  property :group, required: false # 'start' | 'startCollapsed' | 'end'
+  property :group, required: false, as: 'string'
 
   # If an attribute 'variablesReference' exists and its value is > 0, the output contains objects which can be retrieved by passing 'variablesReference' to the 'variables' request. The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :variablesReference, required: false
+  property :variablesReference, required: false, as: 'number'
 
   # An optional source location where the output was produced.
   property :source, required: false, as: DAP::Source
 
   # An optional source location line where the output was produced.
-  property :line, required: false
+  property :line, required: false, as: 'number'
 
   # An optional source location column where the output was produced.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # Optional data to report. For the 'telemetry' category the data will be sent to telemetry, for the other categories the data is shown in JSON format.
   property :data, required: false

data/lib/dap/pause_arguments.rb

@@ -1,4 +1,5 @@
+# Arguments for ‘pause’ request.
 class DAP::PauseArguments < DAP::Base
   # Pause execution for this thread.
-  property :threadId
+  property :threadId, as: 'number'
 end

data/lib/dap/process_event_body.rb

@@ -1,12 +1,14 @@
+# The event indicates that the debugger has begun debugging a new process. Either
+# one that it has launched, or one that it has attached to.
 class DAP::ProcessEventBody < DAP::Base
   # The logical name of the process. This is usually the full path to process's executable file. Example: /home/example/myproj/program.js.
-  property :name
+  property :name, as: 'string'
 
   # The system process id of the debugged process. This property will be missing for non-system processes.
-  property :systemProcessId, required: false
+  property :systemProcessId, required: false, as: 'number'
 
   # If true, the process is running on the same computer as the debug adapter.
-  property :isLocalProcess, required: false
+  property :isLocalProcess, required: false, as: 'boolean'
 
   # Describes how the debug engine started debugging this process.
   # Values:
@@ -14,8 +16,8 @@ class DAP::ProcessEventBody < DAP::Base
   # 'attach': Debugger attached to an existing process.
   # 'attachForSuspendedLaunch': A project launcher component has launched a new process in a suspended state and then asked the debugger to attach.
   # etc.
-  property :startMethod, required: false # 'launch' | 'attach' | 'attachForSuspendedLaunch'
+  property :startMethod, required: false, as: 'string'
 
   # The size of a pointer or address for this process, in bits. This value may be used by clients when formatting addresses for display.
-  property :pointerSize, required: false
+  property :pointerSize, required: false, as: 'number'
 end

data/lib/dap/progress_end_event_body.rb

@@ -1,7 +1,10 @@
+# The event signals the end of the progress reporting with an optional final
+# message. This event should only be sent if the client has passed the value true
+# for the ‘supportsProgressReporting’ capability of the ‘initialize’ request.
 class DAP::ProgressEndEventBody < DAP::Base
   # The ID that was introduced in the initial 'ProgressStartEvent'.
-  property :progressId
+  property :progressId, as: 'string'
 
   # Optional, more detailed progress message. If omitted, the previous message (if any) is used.
-  property :message, required: false
+  property :message, required: false, as: 'string'
 end

data/lib/dap/progress_start_event_body.rb

@@ -1,24 +1,30 @@
+# The event signals that a long running operation is about to start and provides
+# additional information for the client to set up a corresponding progress and
+# cancellation UI. The client is free to delay the showing of the UI in order to
+# reduce flicker. This event should only be sent if the client has passed the
+# value true for the ‘supportsProgressReporting’ capability of the ‘initialize’
+# request.
 class DAP::ProgressStartEventBody < DAP::Base
   # An ID that must be used in subsequent 'progressUpdate' and 'progressEnd' events to make them refer to the same progress reporting.
   # IDs must be unique within a debug session.
-  property :progressId
+  property :progressId, as: 'string'
 
   # Mandatory (short) title of the progress reporting. Shown in the UI to describe the long running operation.
-  property :title
+  property :title, as: 'string'
 
   # The request ID that this progress report is related to. If specified a debug adapter is expected to emit
   # progress events for the long running request until the request has been either completed or cancelled.
   # If the request ID is omitted, the progress report is assumed to be related to some general activity of the debug adapter.
-  property :requestId, required: false
+  property :requestId, required: false, as: 'number'
 
   # If true, the request that reports progress may be canceled with a 'cancel' request.
   # So this property basically controls whether the client should use UX that supports cancellation.
   # Clients that don't support cancellation are allowed to ignore the setting.
-  property :cancellable, required: false
+  property :cancellable, required: false, as: 'boolean'
 
   # Optional, more detailed progress message.
-  property :message, required: false
+  property :message, required: false, as: 'string'
 
   # Optional progress percentage to display (value range: 0 to 100). If omitted no percentage will be shown.
-  property :percentage, required: false
+  property :percentage, required: false, as: 'number'
 end

data/lib/dap/progress_update_event_body.rb

@@ -1,10 +1,16 @@
+# The event signals that the progress reporting needs to updated with a new
+# message and/or percentage. The client does not have to update the UI
+# immediately, but the clients needs to keep track of the message and/or
+# percentage values. This event should only be sent if the client has passed the
+# value true for the ‘supportsProgressReporting’ capability of the ‘initialize’
+# request.
 class DAP::ProgressUpdateEventBody < DAP::Base
   # The ID that was introduced in the initial 'progressStart' event.
-  property :progressId
+  property :progressId, as: 'string'
 
   # Optional, more detailed progress message. If omitted, the previous message (if any) is used.
-  property :message, required: false
+  property :message, required: false, as: 'string'
 
   # Optional progress percentage to display (value range: 0 to 100). If omitted no percentage will be shown.
-  property :percentage, required: false
+  property :percentage, required: false, as: 'number'
 end

data/lib/dap/protocol_message.rb

@@ -1,4 +1,7 @@
+# Base class of requests, responses, and events.
 class DAP::ProtocolMessage < DAP::Base
+  # Valid protocol message types.
+  # @return [Hash<Symbol,Class>]
   def self.types
     @types ||= {
       request: DAP::Request,
@@ -7,6 +10,8 @@ class DAP::ProtocolMessage < DAP::Base
     }
   end
 
+  # Create a protocol message from attribute values.
+  # @param values [Hash] the attribute values
   def self.from(values)
     build(values) do |v|
       key = v[:type]&.to_sym
@@ -17,8 +22,14 @@ class DAP::ProtocolMessage < DAP::Base
     end
   end
 
-  property :seq, :type
+  # Sequence number (also known as message ID). For protocol messages of type
+  # 'request' this ID can be used to cancel the request.
+  property :seq, as: 'number'
 
+  # Message type.
+  property :type, as: 'string'
+
+  # (see Base#initialize)
   def initialize(values)
     super(values)
     @seq = values[:seq] || DAP::ProtocolMessage.seq

data/lib/dap/read_memory_arguments.rb

@@ -1,10 +1,11 @@
+# Arguments for ‘readMemory’ request.
 class DAP::ReadMemoryArguments < DAP::Base
   # Memory reference to the base location from which data should be read.
-  property :memoryReference
+  property :memoryReference, as: 'string'
 
   # Optional offset (in bytes) to be applied to the reference location before reading data. Can be negative.
-  property :offset, required: false
+  property :offset, required: false, as: 'number'
 
   # Number of bytes to read at the specified location and offset.
-  property :count
+  property :count, as: 'number'
 end

data/lib/dap/read_memory_response_body.rb

@@ -1,12 +1,13 @@
+# Response to ‘readMemory’ request.
 class DAP::ReadMemoryResponseBody < DAP::Base
   # The address of the first byte of data returned.
   # Treated as a hex value if prefixed with '0x', or as a decimal value otherwise.
-  property :address
+  property :address, as: 'string'
 
   # The number of unreadable bytes encountered after the last successfully read byte.
   # This can be used to determine the number of bytes that must be skipped before a subsequent 'readMemory' request will succeed.
-  property :unreadableBytes, required: false
+  property :unreadableBytes, required: false, as: 'number'
 
   # The bytes read from memory, encoded using base64.
-  property :data, required: false
+  property :data, required: false, as: 'string'
 end

data/lib/dap/relation.rb

@@ -1,31 +1,47 @@
+# Relationships between DAP types
 module DAP::Relation
+  # Raises an error if `klazz` is not an allowed DAP type
   def self.supported!(klazz)
     raise "Unsupported property class #{klazz}" unless klazz < DAP::Base || klazz < DAP::Enum
   end
 
+  # Indicates a property is expected to be an array of the specified type
   class Many
+    # The expected element type.
     attr_reader :klazz
 
+    # @param klazz [Class] the expected element type
     def initialize(klazz)
       DAP::Relation.supported!(klazz)
       @klazz = klazz
     end
   end
 
+  # Indicates a property is expected to be one of a set of types
   class OneOf
-    attr_reader :types, :key
+    # The allowed key property values and expected types.
+    attr_reader :types
 
+    # The name of the key property.
+    attr_reader :key
+
+    # @param types [Hash<Symbol, Class>] the allowed key property values and expected types
     def initialize(types)
       types.values.each { |k| DAP::Relation.supported!(k) }
       @types = types
     end
 
+    # Specifies the key property that is used to determine which type is selected.
+    # @param key [Symbol] the name of the key property
     def with(key)
       o = dup
       o.instance_eval { @key = key }
       o
     end
 
+    # Sets the expected type for a specified value of the key property.
+    # @param k [Symbol] the specified value
+    # @param v [Class] the expected type
     def []=(k, v)
       @types[k] = v
     end

data/lib/dap/request.rb

@@ -37,11 +37,15 @@ require_relative 'exception_info_arguments'
 require_relative 'read_memory_arguments'
 require_relative 'disassemble_arguments'
 
+# A client or debug adapter initiated request.
 class DAP::Request < DAP::ProtocolMessage
+  # (see ProtocolMessage#type)
   def self.type
     'request'
   end
 
+  # Allowed request commands and their arguments types.
+  # @return [Hash<Symbol, Class>]
   def self.arguments
     @arguments ||= one_of(
       cancel: DAP::CancelArguments,
@@ -89,6 +93,9 @@ class DAP::Request < DAP::ProtocolMessage
     )
   end
 
+  # The command to execute.
   property :command
+
+  # Object containing arguments for the command.
   property :arguments, as: arguments.with(:command)
 end

data/lib/dap/response.rb

@@ -25,11 +25,15 @@ require_relative 'exception_info_response_body'
 require_relative 'read_memory_response_body'
 require_relative 'disassemble_response_body'
 
+# Response for a request.
 class DAP::Response < DAP::ProtocolMessage
+  # (see ProtocolMessage#type)
   def self.type
     'response'
   end
 
+  # Allowed response commands and their body types.
+  # @return [Hash<Symbol, Class>]
   def self.bodies
     @bodies ||= one_of(
       initialize: DAP::Capabilities,
@@ -78,12 +82,29 @@ class DAP::Response < DAP::ProtocolMessage
     )
   end
 
+  # (see Base#validate!)
   def validate!
     return unless success
 
     super
   end
 
-  property :request_seq, :success, :command, :message
+  # Sequence number of the corresponding request.
+  property :request_seq
+
+  # Outcome of the request.
+  # If true, the request was successful and the 'body' attribute may contain the result of the request.
+  # If the value is false, the attribute 'message' contains the error in short form and the 'body' may contain additional information (see 'ErrorResponse.body.error').
+  property :success
+
+  # The command requested.
+  property :command
+
+  # Contains the raw error in short form if 'success' is false.
+  # This raw error might be interpreted by the frontend and is not shown in the UI.
+  # Some predefined values exist.
+  property :message
+
+  # Contains request result if success is true and optional error details if success is false.
   property :body, as: bodies.with(:command)
 end

data/lib/dap/restart_frame_arguments.rb

@@ -1,4 +1,5 @@
+# Arguments for ‘restartFrame’ request.
 class DAP::RestartFrameArguments < DAP::Base
   # Restart this stackframe.
-  property :frameId
+  property :frameId, as: 'number'
 end

data/lib/dap/reverse_continue_arguments.rb

@@ -1,4 +1,5 @@
+# Arguments for ‘reverseContinue’ request.
 class DAP::ReverseContinueArguments < DAP::Base
   # Execute 'reverseContinue' for this thread.
-  property :threadId
+  property :threadId, as: 'number'
 end

data/lib/dap/run_in_terminal_request_arguments.rb

@@ -1,17 +1,18 @@
+# Arguments for ‘runInTerminal’ request.
 class DAP::RunInTerminalRequestArguments < DAP::Base
   # What kind of terminal to launch.
   # Values: 'integrated', 'external', etc.
-  property :kind, required: false # 'integrated' | 'external'
+  property :kind, required: false, as: 'string'
 
   # Optional title of the terminal.
-  property :title, required: false
+  property :title, required: false, as: 'string'
 
   # Working directory of the command.
-  property :cwd
+  property :cwd, as: 'string'
 
   # List of arguments. The first argument is the command to run.
-  property :args
+  property :args, as: 'string[]'
 
   # Environment key-value pairs that are added to or removed from the default environment.
-  property :env, required: false # { [key: string]: string | null; }
+  property :env, required: false
 end

data/lib/dap/run_in_terminal_response_body.rb

@@ -1,7 +1,8 @@
+# Response to ‘runInTerminal’ request.
 class DAP::RunInTerminalResponseBody < DAP::Base
   # The process ID. The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :processId, required: false
+  property :processId, required: false, as: 'number'
 
   # The process ID of the terminal shell. The value should be less than or equal to 2147483647 (2^31 - 1).
-  property :shellProcessId, required: false
+  property :shellProcessId, required: false, as: 'number'
 end

data/lib/dap/scope.rb

@@ -1,8 +1,10 @@
 require_relative 'source'
 
+# A Scope is a named container for variables. Optionally a scope can map to a
+# source or a range within a source.
 class DAP::Scope < DAP::Base
   # Name of the scope such as 'Arguments', 'Locals', or 'Registers'. This string is shown in the UI as is and can be translated.
-  property :name
+  property :name, as: 'string'
 
   # An optional hint for how to present this scope in the UI. If this attribute is missing, the scope is shown with a generic UI.
   # Values:
@@ -10,34 +12,34 @@ class DAP::Scope < DAP::Base
   # 'locals': Scope contains local variables.
   # 'registers': Scope contains registers. Only a single 'registers' scope should be returned from a 'scopes' request.
   # etc.
-  property :presentationHint, required: false # 'arguments' | 'locals' | 'registers' | string
+  property :presentationHint, required: false, as: 'string'
 
   # The variables of this scope can be retrieved by passing the value of variablesReference to the VariablesRequest.
-  property :variablesReference
+  property :variablesReference, as: 'number'
 
   # The number of named variables in this scope.
   # The client can use this optional information to present the variables in a paged UI and fetch them in chunks.
-  property :namedVariables, required: false
+  property :namedVariables, required: false, as: 'number'
 
   # The number of indexed variables in this scope.
   # The client can use this optional information to present the variables in a paged UI and fetch them in chunks.
-  property :indexedVariables, required: false
+  property :indexedVariables, required: false, as: 'number'
 
   # If true, the number of variables in this scope is large or expensive to retrieve.
-  property :expensive
+  property :expensive, as: 'boolean'
 
   # Optional source for this scope.
   property :source, required: false, as: DAP::Source
 
   # Optional start line of the range covered by this scope.
-  property :line, required: false
+  property :line, required: false, as: 'number'
 
   # Optional start column of the range covered by this scope.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # Optional end line of the range covered by this scope.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # Optional end column of the range covered by this scope.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 end