Add documentation

src/backtracer/backtrace/frame.cr

@@ -21,7 +21,7 @@ module Backtracer
 
     def_equals_and_hash @method, @path, @lineno, @column
 
-    # Reconstructs the frame in a readable fashion
+    # Reconstructs the frame in a readable fashion.
     def to_s(io : IO) : Nil
       io << '`' << @method << '`'
       if @path
@@ -37,11 +37,24 @@ module Backtracer
       io << ')'
     end
 
+    # Returns `true` if `path` of this frame is within
+    # the `configuration.src_path`, `false` otherwise.
+    #
+    # See `Configuration#src_path`
     def under_src_path? : Bool
       return false unless src_path = configuration.src_path
       !!path.try(&.starts_with?(src_path))
     end
 
+    # Returns:
+    #
+    # - `path` as is, unless it's absolute - i.e. starts with `/`
+    # - `path` relative to `configuration.src_path` when `under_src_path?` is `true`
+    # - `nil` otherwise
+    #
+    # NOTE: returned path is not required to be `under_src_path?` - see point no. 1
+    #
+    # See `Configuration#src_path`
     def relative_path : String?
       return unless path = @path
       return path unless path.starts_with?('/')
@@ -51,6 +64,13 @@ module Backtracer
       end
     end
 
+    # Returns:
+    #
+    # - `path` as is, if it's absolute - i.e. starts with `/`
+    # - `path` appended to `configuration.src_path`
+    # - `nil` otherwise
+    #
+    # See `Configuration#src_path`
     def absolute_path : String?
       return unless path = @path
       return path if path.starts_with?('/')
@@ -59,16 +79,31 @@ module Backtracer
       end
     end
 
+    # Returns name of the shard from which this frame originated.
+    #
+    # See `Configuration#modules_path_pattern`
     def shard_name : String?
       relative_path
         .try(&.match(configuration.modules_path_pattern))
         .try(&.["name"])
     end
 
+    # Returns `true` if this frame originated from the app source code,
+    # `false` otherwise.
+    #
+    # See `Configuration#in_app_pattern`
     def in_app? : Bool
       !!(path.try(&.matches?(configuration.in_app_pattern)))
     end
 
+    # Returns a tuple consisting of 3 elements - an array of context lines
+    # before the `lineno`, line at `lineno`, and an array of context lines
+    # after the `lineno`. In case of failure it returns `nil`.
+    #
+    # Amount of returned context lines is taken from the *context_lines*
+    # argument if given, or `configuration.context_lines` otherwise.
+    #
+    # See `Configuration#context_lines`
     def context(context_lines : Int32? = nil) : {Array(String), String, Array(String)}?
       context_lines ||= configuration.context_lines
 
@@ -86,6 +121,13 @@ module Backtracer
       end
     end
 
+    # Returns hash with context lines, where line numbers are keys and
+    # the lines itself are values. In case of failure it returns `nil`.
+    #
+    # Amount of returned context lines is taken from the *context_lines*
+    # argument if given, or `configuration.context_lines` otherwise.
+    #
+    # See `Configuration#context`, `Configuration#context_lines`
     def context_hash(context_lines : Int32? = nil) : Hash(Int32, String)?
       return unless context = self.context(context_lines)
       return unless lineno = @lineno

src/backtracer/backtrace/frame/parser.cr

@@ -2,10 +2,13 @@ module Backtracer
   module Backtrace::Frame::Parser
     extend self
 
-    # Parses a single line of a given backtrace, where *unparsed_line* is
+    # Parses a single line of a given backtrace, where *line* is
     # the raw line from `caller` or some backtrace.
     #
-    # Returns the parsed backtrace frame on success or `nil` otherwise.
+    # Accepts options:
+    # - `configuration`: `Configuration` object - uses `Backtracer.configuration` if `nil`
+    #
+    # Returns parsed `Backtrace::Frame` on success or `nil` otherwise.
     def parse?(line : String, **options) : Backtrace::Frame?
       return unless Configuration::LINE_PATTERNS.any? &.match(line)
 
@@ -20,6 +23,7 @@ module Backtracer
         configuration: options[:configuration]?
     end
 
+    # Same as `parse` but raises `ArgumentError` on error.
     def parse(line : String, **options) : Backtrace::Frame
       parse?(line, **options) ||
         raise ArgumentError.new("Error parsing line: #{line.inspect}")

src/backtracer/backtrace/parser.cr

@@ -2,6 +2,14 @@ module Backtracer
   module Backtrace::Parser
     extend self
 
+    # Parses *backtrace* (possibly obtained as a return value
+    # from `caller` or `Exception#backtrace` methods).
+    #
+    # Accepts options:
+    # - `configuration`: `Configuration` object - uses `Backtracer.configuration` if `nil`
+    # - `filters`: additional line filters - see `Configuration#line_filters`
+    #
+    # Returns parsed `Backtrace` object or raises `ArgumentError` otherwise.
     def parse(backtrace : Array(String), **options) : Backtrace
       configuration = options[:configuration]? || Backtracer.configuration
 

src/backtracer/configuration.cr

@@ -54,23 +54,36 @@ module Backtracer
     }
 
     # Used in `#in_app_pattern`.
+    #
+    # See `Frame#under_src_path?`
     property src_path : String? = {{ Process::INITIAL_PWD }}
 
     # Directories to be recognized as part of your app. e.g. if you
     # have an `engines` dir at the root of your project, you may want
     # to set this to something like `/(src|engines)/`
+    #
+    # See `Frame#in_app?`
     property app_dirs_pattern = /src/
 
-    # `Regex` pattern matched against `Backtrace::Frame#file`.
+    # `Regex` pattern matched against `Backtrace::Frame#path`.
+    #
+    # See `Frame#in_app?`
     property in_app_pattern : Regex { /^(#{src_path}\/)?(#{app_dirs_pattern})/ }
 
     # Path pattern matching directories to be recognized as your app modules.
     # Defaults to standard Shards setup (`lib/shard-name/...`).
+    #
+    # See `Frame#shard_name`
     property modules_path_pattern = /^lib\/(?<name>[^\/]+)\/(?:.+)/
 
-    # Number of lines of code context to capture, or `nil` for none.
+    # Number of lines of code context to return by default, or `nil` for none.
+    #
+    # See `Frame#context`
     property context_lines : Int32? = 5
 
+    # Array of procs used for filtering backtrace lines before parsing.
+    # Each filter is expected to return a string, which is then passed
+    # onto the next filter, or ignored althoghether if `nil` is returned.
     getter(line_filters) {
       [
         ->(line : String) { line unless line.matches?(IGNORED_LINES_PATTERN) },