Add yard documentation

Author: AnotherRegularDude

.github/workflows/test.yml

@@ -30,6 +30,8 @@ jobs:
         run: bundle exec ci-helper RunSpecs
       - name: Audit
         run: bundle exec ci-helper BundlerAudit
+      - name: Documentation coverage
+        run: bundle exec rake doc:coverage
       - name: Coveralls
         uses: coverallsapp/github-action@master
         with:

Gemfile

@@ -16,3 +16,4 @@ gem "rspec-json_matcher"
 gem "rubocop-config-umbrellio"
 gem "simplecov"
 gem "simplecov-lcov"
+gem "yard"

Gemfile.lock

@@ -154,6 +154,9 @@ GEM
       sequel
       symbiont-ruby
     unicode-display_width (2.1.0)
+    webrick (1.7.0)
+    yard (0.9.27)
+      webrick (~> 1.7.0)
     zeitwerk (2.5.1)
 
 PLATFORMS
@@ -172,6 +175,7 @@ DEPENDENCIES
   sentry-gruf!
   simplecov
   simplecov-lcov
+  yard
 
 BUNDLED WITH
    2.3.0

Rakefile

@@ -3,8 +3,33 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 require "rubocop/rake_task"
+require "yard"
+
+ROOT = Pathname.new(__FILE__).join("..")
 
 RSpec::Core::RakeTask.new(:spec)
 RuboCop::RakeTask.new(:lint)
 
+YARD::Rake::YardocTask.new(:doc) do |t|
+  t.files = Dir[ROOT.join("lib/**/*.rb")]
+  t.options = %w[--private]
+end
+
+namespace :doc do
+  desc "Check documentation coverage"
+  task coverage: :doc do
+    YARD::Registry.load
+    objs = YARD::Registry.select do |o|
+      puts "pending #{o}" if /TODO|FIXME|@pending/.match?(o.docstring)
+      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 spec]

lib/sentry/gruf.rb

@@ -5,7 +5,11 @@
 require "sentry-ruby"
 require "sentry/integrable"
 
+# Namespace, used by the `sentry-ruby-core` gem.
+# @see https://rubydoc.info/gems/sentry-ruby-core Sentry documentation
 module Sentry
+  # gruf-sentry is a library that provides both client-side and server-side interceptors
+  # that send uncaught error data to Sentry.
   module Gruf
     extend Integrable
     register_integration name: "gruf", version: Sentry::Gruf::VERSION

lib/sentry/gruf/client_interceptor.rb

@@ -2,7 +2,19 @@
 
 module Sentry
   module Gruf
+    # Interceptor for the Gruf client.
+    # Please note that the interceptor itself does not send errors to Sentry.
+    # It simply tags some information about the last request made through the client.
+    # Just add this interceptor to the array of used interceptors as the first element.
+    # @example Use client interceptor
+    #   client = ::Gruf::Client.new(
+    #     service: Some::Service,
+    #     client_options: {
+    #       interceptors: [Sentry::Gruf::ClientInterceptor.new, OtherInterceptors.new]
+    #     }
+    #   )
     class ClientInterceptor < ::Gruf::Interceptors::ClientInterceptor
+      # @param request_context [Gruf::Outbound::RequestContext]
       def call(request_context:)
         ::Sentry.configure_scope do |scope|
           scope.set_tags(

lib/sentry/gruf/server_interceptor.rb

@@ -2,7 +2,18 @@
 
 module Sentry
   module Gruf
+    # Interceptor for Gruf wrapper of gRPC server.
+    # It handles all uncaught exceptions and sent them to the Sentry.
+    # Add this interceptor to the begining of interceptors stack.
+    # @example Use server interceptor
+    #   Gruf.configure do |config|
+    #     config.interceptors.clear
+    #     config.interceptors.use(Sentry::Gruf::ServerInterceptor)
+    #   end
     class ServerInterceptor < ::Gruf::Interceptors::ServerInterceptor
+      # Required method by Gruf interceptor specification.
+      # @see https://rubydoc.info/gems/gruf/Gruf/Interceptors/ServerInterceptor Gruf documentation
+      # @yield Perform request logic
       def call
         yield
       rescue Exception => e

lib/sentry/gruf/version.rb

@@ -2,6 +2,17 @@
 
 module Sentry
   module Gruf
+    # Current gruf-sentry version
+    #
+    # 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 enough to specify '~> a.b'
+    # if private API was not used and to specify '~> a.b.c' if it was
     VERSION = "1.0.0"
   end
 end