Added documentation (#10)

* prepared version dump to next release

1.0.0a would not be launched immediately, but version should be bumped
1.0.0a would be affected by big back-incompatible changes in #9, so it
would be a good time to increment majorest version. Hovewer, i'll
increment it now to simplify Changelog usage.

* Added Changelog.md

* added doc:coverage task into rake default to check yard coverage

* done

* fixed bugs and updated json dependency for ruby 2.4 compatibility

* update travis build matrix to actual supported versions

* updated rubocop to 0.49

.rubocop.yml

@@ -2,5 +2,6 @@ AllCops:
   Exclude:
     - bin/**/*
   TargetRubyVersion: 2.3
+
 Style/Documentation:
   Enabled: false

.travis.yml

@@ -1,5 +1,6 @@
 sudo: false
 language: ruby
 rvm:
-  - 2.3.1
+  - 2.3.4
+  - 2.4.1
 before_install: gem install bundler -v 1.12.5

Changelog.md

@@ -0,0 +1,47 @@
+# Lamian version changes (since 0.1.0)
+
+Update this on a pull request, under Lamian::VERSION
+(also known as next version). If this constant would be changed without release,
+i'll update it here too
+
+## 1.0.0alpha
+
+Add your changes here
+
+
+## 0.3.3
+
+* 8136689 fixed crashes when dump used outside lamian context
+
+
+## 0.3.2
+
+* e57e6cec Changed rails dependency from ~> 4.2 to >= 4.2
+
+
+## 0.3.1
+
+* 34ca83b5 Fixed formatting
+
+Stabilized formatting api, which removes control sequences from loggers data.
+E.g. "[23mNice, lol[0m\n" becomes "Nice, lol\n"
+
+
+## 0.3.0
+
+* d24f895b API update
+
+Updated API, so lamian is now forced to be used with block.
+It also simplified usage outside a middleware
+
+
+## 0.2.0
+* 3166517e Added integrtation with rails
+
+Injected middleware before ExceptionNotification, so ExceptionNotification
+can use current log without any configuration.
+Also added some views
+
+
+## 0.1.0
+* 62eb8685 Made test version to check it's integration with rails application

Gemfile

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 # Specify your gem's dependencies in lamian.gemspec

Rakefile

@@ -1,9 +1,49 @@
 # frozen_string_literal: true
+
 require 'bundler/gem_tasks'
 require 'rspec/core/rake_task'
 require 'rubocop/rake_task'
+require 'yard'
+require 'pathname'
+require 'launchy'
+require 'uri'
+
+ROOT = Pathname.new(__FILE__).join('..')
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new(:lint)
 
-task default: %i(lint spec)
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = Dir[ROOT.join('lib/**/*.rb')]
+  t.options = %w[--private]
+end
+
+def open_in_browser(path)
+  Launchy.open(URI.join('file:///', path.to_s))
+end
+
+namespace :doc do
+  desc 'open doc'
+  task open: :doc do
+    open_in_browser ROOT.join('doc/frames.html')
+  end
+
+  desc 'checks doc coverage'
+  task coverage: :doc do
+    # ideally you've already generated the database to .load it
+    # if not, have this task depend on the docs task.
+    YARD::Registry.load
+    objs = YARD::Registry.select do |o|
+      puts "pending #{o}" if o.docstring =~ /TODO|FIXME|@pending/
+      o.docstring.blank?
+    end
+
+    next if objs.empty?
+    puts 'No documentation found for:'
+    objs.each { |x| puts "\t#{x}" }
+
+    raise '100% document coverage required'
+  end
+end
+
+task default: %i[lint doc:coverage spec]

lamian.gemspec

@@ -1,5 +1,6 @@
 # coding: utf-8
 # frozen_string_literal: true
+
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require 'lamian/version'
@@ -24,7 +25,10 @@ Gem::Specification.new do |spec|
   spec.add_development_dependency 'bundler', '~> 1.12'
   spec.add_development_dependency 'rake', '~> 10.0'
   spec.add_development_dependency 'rspec', '~> 3.0'
-  spec.add_development_dependency 'rubocop', '~> 0.45'
+  spec.add_development_dependency 'rubocop', '~> 0.49'
   spec.add_development_dependency 'pry', '~> 0.10'
   spec.add_development_dependency 'coveralls', '~> 0.8'
+  spec.add_development_dependency 'yard', '~> 0.9'
+  spec.add_development_dependency 'launchy', '~> 2.4.3'
+  spec.add_development_dependency 'json', '>= 2.1.0'
 end

lib/lamian.rb

@@ -1,5 +1,9 @@
 # frozen_string_literal: true
 
+# Lamian is an in-memory logger, which content could be released
+# for error messages.
+# It is designed to work in pair with `exception_notification` gem inside
+# rails aplications
 module Lamian
   autoload :VERSION, 'lamian/version'
   autoload :Config, 'lamian/config'
@@ -10,25 +14,45 @@ module Lamian
   require 'lamian/engine'
 
   class << self
+    # Yields curent configuration if block given
+    # @example
+    #   Lamian.configure do |config|
+    #     config.formatter = MyFormatter.new
+    #   end
+    # @yield [config] current configuration
+    # @yieldparam config [Lamian::Config]
+    # @return [Lamian::Config] current configuration
     def configure
       @config ||= Config.new
       yield(@config) if block_given?
       @config
     end
     alias config configure
 
+    # Extends logger instance to tee it's output to Lamian logger
+    # @param other_logger [Logger] logger to extend
     def extend_logger(other_logger)
       other_logger.extend(Lamian::LoggerExtension)
     end
 
+    # @api private
+    # Gives access to current logger
+    # @return [Lamian::Logger] current logger
     def logger
       Lamian::Logger.current
     end
 
+    # Collects logs sent inside block
     def run
       logger.run { yield }
     end
 
+    # Dumps log collected in this run
+    # @option format [Symbol]
+    #   requested format of log. At this point, returns raw log if falsey
+    #   or log without controll sequences (such as '[23m') if truthy
+    #   value given (for now)
+    # @return formatted log (String by default)
     def dump(format: nil)
       logger.dump(format: format)
     end

lib/lamian/config.rb

@@ -1,7 +1,11 @@
 # frozen_string_literal: true
+
 require 'logger'
 
 module Lamian
+  # General lamian configuration class
+  # @attr formatter [Logger::Foramtter]
+  #   formatter to use in lamian, global
   Config = Struct.new(:formatter) do
     def initialize
       self.formatter = ::Logger::Formatter.new

lib/lamian/engine.rb

@@ -1,9 +1,14 @@
 # frozen_string_literal: true
+
 require 'rails'
 require 'exception_notification'
 require 'exception_notification/rails'
 
 module Lamian
+  # Rails engine, which injects middleware and appends
+  # lamian views to rails library.
+  # Lamian views are used in exception_notifier to provide
+  # request_log section
   class Engine < ::Rails::Engine
     config.app_middleware.insert_before(
       ExceptionNotification::Rack,

lib/lamian/logger.rb

@@ -3,7 +3,19 @@
 require 'logger'
 
 module Lamian
+  # @api private
+  # Provides thread-local loggers to catch teed messages from
+  # regular loggers.
+  # Uses :__lamian_logger thread variable
+  # @attr level [Int]
+  #   current log level, implicitly set to zero
+  # @attr logdevs [Array(StringIO)]
+  #   stack of log devices used to store logs
+  # @attr formatter [Logger::Formatter]
+  #   formatter, inherited from Lamian.config
   class Logger < ::Logger
+    # Provides access to logger bound to curent thread
+    # @return [Lamian::Logger] current logger
     def self.current
       Thread.current[:__lamian_logger] ||= new
     end
@@ -14,17 +26,28 @@ def initialize
       self.formatter = Lamian.config.formatter
     end
 
+    # @see Lamian.run
+    # Collects logs sent inside block
     def run
       push_logdev(StringIO.new)
       yield
     ensure
       pop_logdev
     end
 
+    # Part of Logger api, entry point for all logs
+    # extened to run on each log device in stack
     def add(*args, &block)
       each_logdev { super(*args, &block) }
     end
 
+    # @see Lamian.dump
+    # Dumps log collected in this run
+    # @option format [Symbol]
+    #   requested format of log. At this point, returns raw log if falsey
+    #   or log without controll sequences (such as '[23m') if truthy
+    #   value given (for now)
+    # @return formatted log (String by default)
     def dump(format: nil)
       result = logdevs[-1]&.string&.dup
       apply_format!(format, result)
@@ -35,20 +58,34 @@ def dump(format: nil)
 
     attr_accessor :level, :logdevs, :formatter
 
-    def apply_format!(format, result)
+    # Formats string using given format
+    # @todo create `formatters` interface to allow real format selection
+    # @note
+    #   `format` is now checked only for thruthyness. Please, use
+    #   `:text` format to keep it same after `formatters` interface integration
+    # @param format [Symbol] requested format, e.g. `:text`
+    # @param string [String] string to be changed
+    # @return avoid return value usage
+    def apply_format!(format, string)
       return unless format
-      return unless result
-      result.gsub!(/\[\d{1,2}m/, '')
+      return unless string
+      string.gsub!(/\[\d{1,2}m/, '')
     end
 
+    # Pushes new logdev in the start of #run call
+    # @param logdev [StringIO] new StringIO
     def push_logdev(logdev)
       logdevs << logdev
     end
 
+    # Pops logdev in the end of #run call
+    # @return [StringIO] logdev
     def pop_logdev
       logdevs.pop
     end
 
+    # Runs specific block with all logdevs in stack to
+    # populate them all
     def each_logdev
       logdevs.each do |logdev|
         @logdev = logdev

lib/lamian/logger_extension.rb

@@ -1,6 +1,9 @@
 # frozen_string_literal: true
+
 module Lamian
+  # Provides extension to loggers, which should be teed to lamian
   module LoggerExtension
+    # Extension to Logger#add method, which tees info into lamian
     def add(*args, &block)
       Logger.current.add(*args, &block)
       super

lib/lamian/middleware.rb

@@ -1,10 +1,17 @@
 # frozen_string_literal: true
+
 module Lamian
+  # Provides rack middleware, which allows to colelct request logs
+  # @attr app [Proc] stored application
   class Middleware
+    # @param app [Proc] stored application
     def initialize(app)
       self.app = app
     end
 
+    # wraps application inside lamian context and calls it
+    # @param env [Hash] left intact
+    # @return result of app.call
     def call(env)
       Lamian.run { app.call(env) }
     end

lib/lamian/version.rb

@@ -1,4 +1,17 @@
 # frozen_string_literal: true
+
 module Lamian
-  VERSION = '0.3.3'
+  # Current lamian vewrsion
+  #
+  # format: 'a.b.c' with possible suffixes such as alpha
+  # * a is for major version, it is guaranteed to be changed
+  #   if back-compatibility of public API is broken
+  # * b is for minor version, it is guaranteed to be changed
+  #   on public API changes and also if private API
+  #   back-compatibility is broken
+  # * c is for incremental version, it is updated in other cases
+  # According to this, it is enought to specify '~> a.b'
+  # if private API was not used and to specify '~> a.b.c' if it was
+
+  VERSION = '1.0.0alpha'
 end

spec/lamian/logger_spec.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 describe Lamian::Logger do
   describe '#dump', :cool_loggers do
     specify 'with #run' do

spec/lamian/middleware_spec.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 describe Lamian::Middleware do
   let(:app) { double(:app) }
   let(:env) { double(:env) }

spec/lamian_spec.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 describe Lamian do
   it 'has a version number' do
     expect(Lamian::VERSION).not_to be nil

spec/spec_helper.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 require 'bundler/setup'
 require 'logger'
 require 'pry'