Document Client and Scope classes. (#1659)

* Document Client's public APIs

* Document Scope's public APIs

sentry-ruby/lib/sentry-ruby.rb

@@ -101,7 +101,20 @@ def register_integration(name, version)
 
     extend Forwardable
 
+    # @!method configuration
+    #   @see Client#configuration
+    # @!method send_event
+    #   @see Client#send_event
     def_delegators :get_current_client, :configuration, :send_event
+
+    # @!method set_tags
+    #   @see Scope#set_tags
+    # @!method set_extras
+    #   @see Scope#set_extras
+    # @!method set_user
+    #   @see Scope#set_user
+    # @!method set_context
+    #   @see Scope#set_context
     def_delegators :get_current_scope, :set_tags, :set_extras, :set_user, :set_context
 
     ##### Main APIs #####

sentry-ruby/lib/sentry/client.rb

@@ -6,11 +6,18 @@ module Sentry
   class Client
     include LoggingHelper
 
-    attr_reader :transport, :configuration
+    # The Transport object that'll send events for the client.
+    # @return [Transport]
+    attr_reader :transport
+
+    # The Configuration object that's used for configuring the client and its transport.
+    # @return [Configuration]
+    attr_reader :configuration
 
     # @deprecated Use Sentry.logger to retrieve the current logger instead.
     attr_reader :logger
 
+    # @param configuration [Configuration]
     def initialize(configuration)
       @configuration = configuration
       @logger = configuration.logger
@@ -28,6 +35,11 @@ def initialize(configuration)
       end
     end
 
+    # Applies the given scope's data to the event and sends it to Sentry.
+    # @param event [Event] the event to be sent.
+    # @param scope [Scope] the scope with contextual data that'll be applied to the event before it's sent.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event, nil]
     def capture_event(event, scope, hint = {})
       return unless configuration.sending_allowed?
 
@@ -60,6 +72,10 @@ def capture_event(event, scope, hint = {})
       nil
     end
 
+    # Initializes an Event object with the given exception. Returns `nil` if the exception's class is excluded from reporting.
+    # @param exception [Exception] the exception to be reported.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event, nil]
     def event_from_exception(exception, hint = {})
       integration_meta = Sentry.integrations[hint[:integration]]
       return unless @configuration.exception_class_allowed?(exception)
@@ -70,13 +86,20 @@ def event_from_exception(exception, hint = {})
       end
     end
 
+    # Initializes an Event object with the given message.
+    # @param message [String] the message to be reported.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback and the scope's event processors.
+    # @return [Event]
     def event_from_message(message, hint = {}, backtrace: nil)
       integration_meta = Sentry.integrations[hint[:integration]]
       event = Event.new(configuration: configuration, integration_meta: integration_meta, message: message)
       event.add_threads_interface(backtrace: backtrace || caller)
       event
     end
 
+    # Initializes an Event object with the given Transaction object.
+    # @param transaction [Transaction] the transaction to be recorded.
+    # @return [TransactionEvent]
     def event_from_transaction(transaction)
       TransactionEvent.new(configuration: configuration).tap do |event|
         event.transaction = transaction.name
@@ -89,6 +112,10 @@ def event_from_transaction(transaction)
       end
     end
 
+    # Sends the event to Sentry.
+    # @param event [Event] the event to be sent.
+    # @param hint [Hash] the hint data that'll be passed to `before_send` callback.
+    # @return [Event]
     def send_event(event, hint = nil)
       event_type = event.is_a?(Event) ? event.type : event["type"]
 
@@ -115,6 +142,10 @@ def send_event(event, hint = nil)
       raise
     end
 
+    # Generates a Sentry trace for distribted tracing from the given Span.
+    # Returns `nil` if `config.propagate_traces` is `false`.
+    # @param span [Span] the span to generate trace from.
+    # @return [String, nil]
     def generate_sentry_trace(span)
       return unless configuration.propagate_traces
 

sentry-ruby/lib/sentry/scope.rb

@@ -11,15 +11,22 @@ class Scope
 
     attr_reader(*ATTRIBUTES)
 
+    # @param max_breadcrumbs [Integer] the maximum number of breadcrumbs to be stored in the scope.
     def initialize(max_breadcrumbs: nil)
       @max_breadcrumbs = max_breadcrumbs
       set_default_value
     end
 
+    # Resets the scope's attributes to defaults.
+    # @return [void]
     def clear
       set_default_value
     end
 
+    # Applies stored attributes and event processors to the given event.
+    # @param event [Event]
+    # @param hint [Hash] the hint data that'll be passed to event processors.
+    # @return [Event]
     def apply_to_event(event, hint = nil)
       event.tags = tags.merge(event.tags)
       event.user = user.merge(event.user)
@@ -45,14 +52,20 @@ def apply_to_event(event, hint = nil)
       event
     end
 
+    # Adds the breadcrumb to the scope's breadcrumbs buffer.
+    # @param breadcrumb [Breadcrumb]
+    # @return [void]
     def add_breadcrumb(breadcrumb)
       breadcrumbs.record(breadcrumb)
     end
 
+    # Clears the scope's breadcrumbs buffer
+    # @return [void]
     def clear_breadcrumbs
       set_new_breadcrumb_buffer
     end
 
+    # @return [Scope]
     def dup
       copy = super
       copy.breadcrumbs = breadcrumbs.dup
@@ -66,6 +79,9 @@ def dup
       copy
     end
 
+    # Updates the scope's data from a given scope.
+    # @param scope [Scope]
+    # @return [void]
     def update_from_scope(scope)
       self.breadcrumbs = scope.breadcrumbs
       self.contexts = scope.contexts
@@ -77,6 +93,14 @@ def update_from_scope(scope)
       self.span = scope.span
     end
 
+    # Updates the scope's data from the given options.
+    # @param contexts [Hash]
+    # @param extras [Hash]
+    # @param tags [Hash]
+    # @param user [Hash]
+    # @param level [String, Symbol]
+    # @param fingerprint [Array]
+    # @return [void]
     def update_from_options(
       contexts: nil,
       extra: nil,
@@ -93,77 +117,127 @@ def update_from_options(
       self.fingerprint = fingerprint if fingerprint
     end
 
+    # Sets the scope's rack_env attribute.
+    # @param env [Hash]
+    # @return [Hash]
     def set_rack_env(env)
       env = env || {}
       @rack_env = env
     end
 
+    # Sets the scope's span attribute.
+    # @param span [Span]
+    # @return [Span]
     def set_span(span)
       check_argument_type!(span, Span)
       @span = span
     end
 
+    # Sets the scope's user attribute.
+    # @param user [Hash]
+    # @return [Hash]
     def set_user(user_hash)
       check_argument_type!(user_hash, Hash)
       @user = user_hash
     end
 
+    # Updates the scope's extras attribute by merging with the old value.
+    # @param extras [Hash]
+    # @return [Hash]
     def set_extras(extras_hash)
       check_argument_type!(extras_hash, Hash)
       @extra.merge!(extras_hash)
     end
 
+    # Adds a new key-value pair to current extras.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Hash]
     def set_extra(key, value)
       set_extras(key => value)
     end
 
+    # Updates the scope's tags attribute by merging with the old value.
+    # @param tags [Hash]
+    # @return [Hash]
     def set_tags(tags_hash)
       check_argument_type!(tags_hash, Hash)
       @tags.merge!(tags_hash)
     end
 
+    # Adds a new key-value pair to current tags.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Hash]
     def set_tag(key, value)
       set_tags(key => value)
     end
 
+    # Updates the scope's contexts attribute by merging with the old value.
+    # @param contexts [Hash]
+    # @return [Hash]
     def set_contexts(contexts_hash)
       check_argument_type!(contexts_hash, Hash)
       @contexts.merge!(contexts_hash) do |key, old, new|
         new.merge(old)
       end
     end
 
+    # Adds a new key-value pair to current contexts.
+    # @param key [String, Symbol]
+    # @param value [Object]
+    # @return [Hash]
     def set_context(key, value)
       check_argument_type!(value, Hash)
       set_contexts(key => value)
     end
 
+    # Sets the scope's level attribute.
+    # @param level [String, Symbol]
+    # @return [void]
     def set_level(level)
       @level = level
     end
 
+    # Appends a new transaction name to the scope.
+    # The "transaction" here does not refer to `Transaction` objects.
+    # @param transaction_name [String]
+    # @return [void]
     def set_transaction_name(transaction_name)
       @transaction_names << transaction_name
     end
 
+    # Returns current transaction name.
+    # The "transaction" here does not refer to `Transaction` objects.
+    # @return [String, nil]
     def transaction_name
       @transaction_names.last
     end
 
+    # Returns the associated Transaction object.
+    # @return [Transaction, nil]
     def get_transaction
       span.transaction if span
     end
 
+    # Returns the associated Span object.
+    # @return [Span, nil]
     def get_span
       span
     end
 
+    # Sets the scope's fingerprint attribute.
+    # @param fingerprint [Array]
+    # @return [Array]
     def set_fingerprint(fingerprint)
       check_argument_type!(fingerprint, Array)
 
       @fingerprint = fingerprint
     end
 
+    # Adds a new event processor [Proc] to the scope.
+    # @param block [Proc]
+    # @return [void]
     def add_event_processor(&block)
       @event_processors << block
     end
@@ -193,8 +267,8 @@ def set_new_breadcrumb_buffer
       @breadcrumbs = BreadcrumbBuffer.new(@max_breadcrumbs)
     end
 
-
     class << self
+      # @return [Hash]
       def os_context
         @os_context ||=
           begin
@@ -208,6 +282,7 @@ def os_context
           end
       end
 
+      # @return [Hash]
       def runtime_context
         @runtime_context ||= {
           name: RbConfig::CONFIG["ruby_install_name"],