ruby-dap 0.1.2 → 0.1.3

data/lib/dap/event.rb

@@ -14,11 +14,15 @@ require_relative 'stopped_event_body'
 require_relative 'terminated_event_body'
 require_relative 'thread_event_body'
 
+# Base class of requests, responses, and events.
 class DAP::Event < DAP::ProtocolMessage
+  # (see ProtocolMessage#type)
   def self.type
     'event'
   end
 
+  # Allowed event kinds and their body types.
+  # @return [Hash<Symbol, Class>]
   def self.bodies
     @bodies ||= one_of(
       initialized: empty,
@@ -40,6 +44,9 @@ class DAP::Event < DAP::ProtocolMessage
     )
   end
 
+  # Type of event.
   property :event
+
+  # Event-specific information.
   property :body, as: bodies.with(:event)
 end

data/lib/dap/exception_break_mode.rb

@@ -1,6 +1,12 @@
+# This enumeration defines all possible conditions when a thrown exception should
+# result in a break.
 class DAP::ExceptionBreakMode < DAP::Enum
+  # never breaks
   NEVER = new('never')
+  # always breaks
   ALWAYS = new('always')
+  # breaks when exception unhandled
   UNHANDLED = new('unhandled')
+  # breaks if the exception is not handled by user code
   USERUNHANDLED = new('userUnhandled')
 end

data/lib/dap/exception_breakpoints_filter.rb

@@ -1,10 +1,12 @@
+# An ExceptionBreakpointsFilter is shown in the UI as an option for configuring
+# how exceptions are dealt with.
 class DAP::ExceptionBreakpointsFilter < DAP::Base
   # The internal ID of the filter. This value is passed to the setExceptionBreakpoints request.
-  property :filter
+  property :filter, as: 'string'
 
   # The name of the filter. This will be shown in the UI.
-  property :label
+  property :label, as: 'string'
 
   # Initial value of the filter. If not specified a value 'false' is assumed.
-  property :default, required: false
+  property :default, required: false, as: 'boolean'
 end

data/lib/dap/exception_details.rb

@@ -1,20 +1,21 @@
 require_relative 'exception_details'
 
+# Detailed information about an exception that has occurred.
 class DAP::ExceptionDetails < DAP::Base
   # Message contained in the exception.
-  property :message, required: false
+  property :message, required: false, as: 'string'
 
   # Short type name of the exception object.
-  property :typeName, required: false
+  property :typeName, required: false, as: 'string'
 
   # Fully-qualified type name of the exception object.
-  property :fullTypeName, required: false
+  property :fullTypeName, required: false, as: 'string'
 
   # Optional expression that can be evaluated in the current scope to obtain the exception object.
-  property :evaluateName, required: false
+  property :evaluateName, required: false, as: 'string'
 
   # Stack trace at the time the exception was thrown.
-  property :stackTrace, required: false
+  property :stackTrace, required: false, as: 'string'
 
   # Details of the exception contained by this exception, if any.
   property :innerException, required: false, as: many(DAP::ExceptionDetails)

data/lib/dap/exception_info_arguments.rb

@@ -1,4 +1,5 @@
+# Arguments for ‘exceptionInfo’ request.
 class DAP::ExceptionInfoArguments < DAP::Base
   # Thread for which exception information should be retrieved.
-  property :threadId
+  property :threadId, as: 'number'
 end

data/lib/dap/exception_info_response_body.rb

@@ -1,12 +1,13 @@
 require_relative 'exception_break_mode'
 require_relative 'exception_details'
 
+# Response to ‘exceptionInfo’ request.
 class DAP::ExceptionInfoResponseBody < DAP::Base
   # ID of the exception that was thrown.
-  property :exceptionId
+  property :exceptionId, as: 'string'
 
   # Descriptive text for the exception provided by the debug adapter.
-  property :description, required: false
+  property :description, required: false, as: 'string'
 
   # Mode that caused the exception notification to be raised.
   property :breakMode, as: DAP::ExceptionBreakMode

data/lib/dap/exception_options.rb

@@ -1,6 +1,7 @@
 require_relative 'exception_path_segment'
 require_relative 'exception_break_mode'
 
+# An ExceptionOptions assigns configuration options to a set of exceptions.
 class DAP::ExceptionOptions < DAP::Base
   # A path that selects a single or multiple exceptions in a tree. If 'path' is missing, the whole tree is selected.
   # By convention the first segment of the path is a category that is used to group exceptions in the UI.

data/lib/dap/exception_path_segment.rb

@@ -1,7 +1,11 @@
+# An ExceptionPathSegment represents a segment in a path that is used to match
+# leafs or nodes in a tree of exceptions. If a segment consists of more than one
+# name, it matches the names provided if ‘negate’ is false or missing or it
+# matches anything except the names provided if ‘negate’ is true.
 class DAP::ExceptionPathSegment < DAP::Base
   # If false or missing this segment matches the names provided, otherwise it matches anything except the names provided.
-  property :negate, required: false
+  property :negate, required: false, as: 'boolean'
 
   # Depending on the value of 'negate' the names that should match or not match.
-  property :names
+  property :names, as: 'string[]'
 end

data/lib/dap/exited_event_body.rb

@@ -1,4 +1,5 @@
+# The event indicates that the debuggee has exited and returns its exit code.
 class DAP::ExitedEventBody < DAP::Base
   # The exit code returned from the debuggee.
-  property :exitCode
+  property :exitCode, as: 'number'
 end

data/lib/dap/function_breakpoint.rb

@@ -1,13 +1,14 @@
+# Properties of a breakpoint passed to the setFunctionBreakpoints request.
 class DAP::FunctionBreakpoint < DAP::Base
   # The name of the function.
-  property :name
+  property :name, as: 'string'
 
   # An optional expression for conditional breakpoints.
   # It is only honored by a debug adapter if the capability 'supportsConditionalBreakpoints' is true.
-  property :condition, required: false
+  property :condition, required: false, as: 'string'
 
   # An optional expression that controls how many hits of the breakpoint are ignored.
   # The backend is expected to interpret the expression as needed.
   # The attribute is only honored by a debug adapter if the capability 'supportsHitConditionalBreakpoints' is true.
-  property :hitCondition, required: false
+  property :hitCondition, required: false, as: 'string'
 end

data/lib/dap/goto_arguments.rb

@@ -1,7 +1,8 @@
+# Arguments for ‘goto’ request.
 class DAP::GotoArguments < DAP::Base
   # Set the goto target for this thread.
-  property :threadId
+  property :threadId, as: 'number'
 
   # The location where the debuggee will continue to run.
-  property :targetId
+  property :targetId, as: 'number'
 end

data/lib/dap/goto_target.rb

@@ -1,22 +1,25 @@
+# A GotoTarget describes a code location that can be used as a target in the
+# ‘goto’ request. The possible goto targets can be determined via the
+# ‘gotoTargets’ request.
 class DAP::GotoTarget < DAP::Base
   # Unique identifier for a goto target. This is used in the goto request.
-  property :id
+  property :id, as: 'number'
 
   # The name of the goto target (shown in the UI).
-  property :label
+  property :label, as: 'string'
 
   # The line of the goto target.
-  property :line
+  property :line, as: 'number'
 
   # An optional column of the goto target.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 
   # An optional end line of the range covered by the goto target.
-  property :endLine, required: false
+  property :endLine, required: false, as: 'number'
 
   # An optional end column of the range covered by the goto target.
-  property :endColumn, required: false
+  property :endColumn, required: false, as: 'number'
 
   # Optional memory reference for the instruction pointer value represented by this target.
-  property :instructionPointerReference, required: false
+  property :instructionPointerReference, required: false, as: 'string'
 end

data/lib/dap/goto_targets_arguments.rb

@@ -1,12 +1,13 @@
 require_relative 'source'
 
+# Arguments for ‘gotoTargets’ request.
 class DAP::GotoTargetsArguments < DAP::Base
   # The source location for which the goto targets are determined.
   property :source, as: DAP::Source
 
   # The line location for which the goto targets are determined.
-  property :line
+  property :line, as: 'number'
 
   # An optional column location for which the goto targets are determined.
-  property :column, required: false
+  property :column, required: false, as: 'number'
 end

data/lib/dap/goto_targets_response_body.rb

@@ -1,5 +1,6 @@
 require_relative 'goto_target'
 
+# Response to ‘gotoTargets’ request.
 class DAP::GotoTargetsResponseBody < DAP::Base
   # The possible goto targets of the specified location.
   property :targets, as: many(DAP::GotoTarget)

data/lib/dap/initialize_request_arguments.rb

@@ -1,41 +1,42 @@
+# Arguments for ‘initialize’ request.
 class DAP::InitializeRequestArguments < DAP::Base
   # The ID of the (frontend) client using this adapter.
-  property :clientID, required: false
+  property :clientID, required: false, as: 'string'
 
   # The human readable name of the (frontend) client using this adapter.
-  property :clientName, required: false
+  property :clientName, required: false, as: 'string'
 
   # The ID of the debug adapter.
-  property :adapterID
+  property :adapterID, as: 'string'
 
   # The ISO-639 locale of the (frontend) client using this adapter, e.g. en-US or de-CH.
-  property :locale, required: false
+  property :locale, required: false, as: 'string'
 
   # If true all line numbers are 1-based (default).
-  property :linesStartAt1, required: false
+  property :linesStartAt1, required: false, as: 'boolean'
 
   # If true all column numbers are 1-based (default).
-  property :columnsStartAt1, required: false
+  property :columnsStartAt1, required: false, as: 'boolean'
 
   # Determines in what format paths are specified. The default is 'path', which is the native format.
   # Values: 'path', 'uri', etc.
-  property :pathFormat, required: false # 'path' | 'uri' | string
+  property :pathFormat, required: false, as: 'string'
 
   # Client supports the optional type attribute for variables.
-  property :supportsVariableType, required: false
+  property :supportsVariableType, required: false, as: 'boolean'
 
   # Client supports the paging of variables.
-  property :supportsVariablePaging, required: false
+  property :supportsVariablePaging, required: false, as: 'boolean'
 
   # Client supports the runInTerminal request.
-  property :supportsRunInTerminalRequest, required: false
+  property :supportsRunInTerminalRequest, required: false, as: 'boolean'
 
   # Client supports memory references.
-  property :supportsMemoryReferences, required: false
+  property :supportsMemoryReferences, required: false, as: 'boolean'
 
   # Client supports progress reporting.
-  property :supportsProgressReporting, required: false
+  property :supportsProgressReporting, required: false, as: 'boolean'
 
   # Client supports the invalidated event.
-  property :supportsInvalidatedEvent, required: false
+  property :supportsInvalidatedEvent, required: false, as: 'boolean'
 end

data/lib/dap/instruction_breakpoint.rb

@@ -1,18 +1,19 @@
+# Properties of a breakpoint passed to the setInstructionBreakpoints request
 class DAP::InstructionBreakpoint < DAP::Base
   # The instruction reference of the breakpoint.
   # This should be a memory or instruction pointer reference from an EvaluateResponse, Variable, StackFrame, GotoTarget, or Breakpoint.
-  property :instructionReference
+  property :instructionReference, as: 'string'
 
   # An optional offset from the instruction reference.
   # This can be negative.
-  property :offset, required: false
+  property :offset, required: false, as: 'number'
 
   # An optional expression for conditional breakpoints.
   # It is only honored by a debug adapter if the capability 'supportsConditionalBreakpoints' is true.
-  property :condition, required: false
+  property :condition, required: false, as: 'string'
 
   # An optional expression that controls how many hits of the breakpoint are ignored.
   # The backend is expected to interpret the expression as needed.
   # The attribute is only honored by a debug adapter if the capability 'supportsHitConditionalBreakpoints' is true.
-  property :hitCondition, required: false
+  property :hitCondition, required: false, as: 'string'
 end

data/lib/dap/invalidated_event_body.rb

@@ -1,10 +1,18 @@
+# This event signals that some state in the debug adapter has changed and requires
+# that the client needs to re-render the data snapshot previously requested. Debug
+# adapters do not have to emit this event for runtime changes like stopped or
+# thread events because in that case the client refetches the new state anyway.
+# But the event can be used for example to refresh the UI after rendering
+# formatting has changed in the debug adapter. This event should only be sent if
+# the debug adapter has received a value true for the ‘supportsInvalidatedEvent’
+# capability of the ‘initialize’ request.
 class DAP::InvalidatedEventBody < DAP::Base
   # Optional set of logical areas that got invalidated. This property has a hint characteristic: a client can only be expected to make a 'best effort' in honouring the areas but there are no guarantees. If this property is missing, empty, or if values are not understand the client should assume a single value 'all'.
-  property :areas, required: false # InvalidatedAreas[]
+  property :areas, required: false, as: 'InvalidatedAreas[]'
 
   # If specified, the client only needs to refetch data related to this thread.
-  property :threadId, required: false
+  property :threadId, required: false, as: 'number'
 
   # If specified, the client only needs to refetch data related to this stack frame (and the 'threadId' is ignored).
-  property :stackFrameId, required: false
+  property :stackFrameId, required: false, as: 'number'
 end

data/lib/dap/launch_request_arguments.rb

@@ -1,6 +1,8 @@
+# Arguments for ‘launch’ request. Additional attributes are implementation
+# specific.
 class DAP::LaunchRequestArguments < DAP::Base
   # If noDebug is true the launch request should launch the program without enabling debugging.
-  property :noDebug, required: false
+  property :noDebug, required: false, as: 'boolean'
 
   # Optional data from the previous, restarted session.
   # The data is sent as the 'restart' attribute of the 'terminated' event.

data/lib/dap/loaded_source_event_body.rb

@@ -1,9 +1,11 @@
 require_relative 'source'
 
+# The event indicates that some source has been added, changed, or removed from
+# the set of all loaded sources.
 class DAP::LoadedSourceEventBody < DAP::Base
   # The reason for the event.
   # Values: 'new', 'changed', 'removed', etc.
-  property :reason # 'new' | 'changed' | 'removed'
+  property :reason, as: 'string'
 
   # The new, changed, or removed source.
   property :source, as: DAP::Source

data/lib/dap/loaded_sources_response_body.rb

@@ -1,5 +1,6 @@
 require_relative 'source'
 
+# Response to ‘loadedSources’ request.
 class DAP::LoadedSourcesResponseBody < DAP::Base
   # Set of loaded sources.
   property :sources, as: many(DAP::Source)

data/lib/dap/message.rb

@@ -1,23 +1,24 @@
+# A structured message object. Used to return errors from requests.
 class DAP::Message < DAP::Base
   # Unique identifier for the message.
-  property :id
+  property :id, as: 'number'
 
   # A format string for the message. Embedded variables have the form '{name}'.
   # If variable name starts with an underscore character, the variable does not contain user data (PII) and can be safely used for telemetry purposes.
-  property :format
+  property :format, as: 'string'
 
   # An object used as a dictionary for looking up the variables in the format string.
-  property :variables, required: false # { [key: string]: string; }
+  property :variables, required: false
 
   # If true send to telemetry.
-  property :sendTelemetry, required: false
+  property :sendTelemetry, required: false, as: 'boolean'
 
   # If true show user.
-  property :showUser, required: false
+  property :showUser, required: false, as: 'boolean'
 
   # An optional url where additional information about this message can be found.
-  property :url, required: false
+  property :url, required: false, as: 'string'
 
   # An optional label that is presented to the user as the UI for opening the url.
-  property :urlLabel, required: false
+  property :urlLabel, required: false, as: 'string'
 end

data/lib/dap/module.rb

@@ -1,28 +1,37 @@
+# A Module object represents a row in the modules view. Two attributes are
+# mandatory: an id identifies a module in the modules view and is used in a
+# ModuleEvent for identifying a module for adding, updating or deleting. The name
+# is used to minimally render the module in the UI. Additional attributes can be
+# added to the module. They will show up in the module View if they have a
+# corresponding ColumnDescriptor. To avoid an unnecessary proliferation of
+# additional attributes with similar semantics but different names we recommend to
+# re-use attributes from the ‘recommended’ list below first, and only introduce
+# new attributes if nothing appropriate could be found.
 class DAP::Module < DAP::Base
   # Unique identifier for the module.
   property :id
 
   # A name of the module.
-  property :name
+  property :name, as: 'string'
 
   # True if the module is optimized.
-  property :isOptimized, required: false
+  property :isOptimized, required: false, as: 'boolean'
 
   # True if the module is considered 'user code' by a debugger that supports 'Just My Code'.
-  property :isUserCode, required: false
+  property :isUserCode, required: false, as: 'boolean'
 
   # Version of Module.
-  property :version, required: false
+  property :version, required: false, as: 'string'
 
   # User understandable description of if symbols were found for the module (ex: 'Symbols Loaded', 'Symbols not found', etc.
-  property :symbolStatus, required: false
+  property :symbolStatus, required: false, as: 'string'
 
   # Logical full path to the symbol file. The exact definition is implementation defined.
-  property :symbolFilePath, required: false
+  property :symbolFilePath, required: false, as: 'string'
 
   # Module created or modified.
-  property :dateTimeStamp, required: false
+  property :dateTimeStamp, required: false, as: 'string'
 
   # Address range covered by this module.
-  property :addressRange, required: false
+  property :addressRange, required: false, as: 'string'
 end

data/lib/dap/module_event_body.rb

@@ -1,9 +1,10 @@
 require_relative 'module'
 
+# The event indicates that some information about a module has changed.
 class DAP::ModuleEventBody < DAP::Base
   # The reason for the event.
   # Values: 'new', 'changed', 'removed', etc.
-  property :reason # 'new' | 'changed' | 'removed'
+  property :reason, as: 'string'
 
   # The new, changed, or removed module. In case of 'removed' only the module id is used.
   property :module, as: DAP::Module