(maint) Add some docs and remove the Style/Documentation exclusions

Author: DavidS

.rubocop.yml

@@ -1,6 +1,5 @@
 ---
 require: rubocop-rspec
-inherit_from: .rubocop_todo.yml
 AllCops:
   TargetRubyVersion: '2.1'
   Include:
@@ -157,4 +156,4 @@ Naming/UncommunicativeMethodParamName:
 
 # This cop breaks syntax highlighting in VSCode
 Layout/ClosingHeredocIndentation:
-  Enabled: false
+  Enabled: false

.rubocop_todo.yml

@@ -12,6 +12,7 @@
 require 'puppet/type'
 require 'puppet/util/network_device'
 
+# This module contains the main API to register and access types, providers and transports.
 module Puppet::ResourceApi
   @warning_count = 0
 

lib/puppet/resource_api.rb

@@ -1,7 +1,12 @@
 require 'puppet/resource_api/type_definition'
 
+# rubocop:disable Style/Documentation
 module Puppet; end
 module Puppet::ResourceApi; end
+# rubocop:enable Style/Documentation
+
+# This class provides access to all common external dependencies of providers and transports.
+# The runtime environment will inject an appropriate implementation.
 class Puppet::ResourceApi::BaseContext
   attr_reader :type
 

lib/puppet/resource_api/base_context.rb

@@ -1,5 +1,7 @@
 require 'puppet/resource_api/base_context'
 
+# Implement Resource API Conext to log through an IO object, defaulting to `$stderr`.
+# There is no access to a device here.
 class Puppet::ResourceApi::IOContext < Puppet::ResourceApi::BaseContext
   def initialize(definition, target = $stderr)
     super(definition)

lib/puppet/resource_api/io_context.rb

@@ -1,6 +1,8 @@
 require 'puppet/resource_api/base_context'
 require 'puppet/util/logging'
 
+# Implement Resource API Conext to log through Puppet facilities
+# and access/expose the puppet process' current device
 class Puppet::ResourceApi::PuppetContext < Puppet::ResourceApi::BaseContext
   def device
     # TODO: evaluate facter_url setting for loading config if there is no `current` NetworkDevice

lib/puppet/resource_api/puppet_context.rb

@@ -1,3 +1,8 @@
+# rubocop:disable Style/Documentation
+module Puppet; end
+module Puppet::ResourceApi; end
+# rubocop:enable Style/Documentation
+
 # Remote target transport API
 module Puppet::ResourceApi::Transport
   def register(schema)