Merge pull request #298 from rodjek/docs

Update code documentation

lib/puppet-lint.rb

@@ -10,6 +10,7 @@
 class PuppetLint::NoCodeError < StandardError; end
 class PuppetLint::NoFix < StandardError; end
 
+# Public: The public interface to puppet-lint.
 class PuppetLint
   # Public: Gets/Sets the String manifest code to be checked.
   attr_accessor :code
@@ -179,9 +180,18 @@ def print_problems
 
   # Public: Define a new check.
   #
-  # name  - A unique name for the check as a Symbol
+  # name  - A unique name for the check as a Symbol.
   # block - The check logic. This must contain a `check` method and optionally
   #         a `fix` method.
+  #
+  # Returns nothing.
+  #
+  # Examples
+  #
+  #   PuppetLint.new_check(:foo) do
+  #     def check
+  #     end
+  #   end
   def self.new_check(name, &block)
     class_name = name.to_s.split('_').map(&:capitalize).join
     klass = PuppetLint.const_set("Check#{class_name}", Class.new(PuppetLint::CheckPlugin))

lib/puppet-lint/bin.rb

@@ -1,10 +1,16 @@
 require 'puppet-lint/optparser'
 
+# Internal: The logic of the puppet-lint bin script, contained in a class for
+# ease of testing.
 class PuppetLint::Bin
   # Public: Initialise a new PuppetLint::Bin.
   #
   # args - An Array of command line argument Strings to be passed to the option
   #        parser.
+  #
+  # Examples
+  #
+  #   PuppetLint::Bin.new(ARGV).run
   def initialize(args)
     @args = args
   end

lib/puppet-lint/checkplugin.rb

@@ -1,8 +1,22 @@
+# Public: A class that contains and provides information for the puppet-lint
+# checks.
+#
+# This class should not be used directly, but instead should be inherited.
+#
+# Examples
+#
+#   class PuppetLint::Plugin::CheckFoo < PuppetLint::CheckPlugin
+#   end
 class PuppetLint::CheckPlugin
+  # Internal: Initialise a new PuppetLint::CheckPlugin.
   def initialize
     @problems = []
   end
 
+  # Internal: Check the manifest for problems and filter out any problems that
+  # should be ignored.
+  #
+  # Returns an Array of problem Hashes.
   def run
     check
 
@@ -17,6 +31,9 @@ def run
     @problems
   end
 
+  # Internal: Fix any problems the check plugin has detected.
+  #
+  # Returns an Array of problem Hashes.
   def fix_problems
     @problems.each do |problem|
       if self.respond_to?(:fix)
@@ -35,46 +52,84 @@ def fix_problems
 
   private
 
+  # Public: Provides the tokenised manifest to the check plugins.
+  #
+  # Returns an Array of PuppetLint::Lexer::Token objects.
   def tokens
     PuppetLint::Data.tokens
   end
 
+  # Public: Provides the resource titles to the check plugins.
+  #
+  # Returns an Array of PuppetLint::Lexer::Token objects.
   def title_tokens
     PuppetLint::Data.title_tokens
   end
 
+  # Public: Provides positional information for any resource declarations in
+  # the tokens array to the check plugins.
+  #
+  # Returns an Array of Hashes containing the position information.
   def resource_indexes
     PuppetLint::Data.resource_indexes
   end
 
+  # Public: Provides positional information for any class definitions in the
+  # tokens array to the check plugins.
+  #
+  # Returns an Array of Hashes containing the position information.
   def class_indexes
     PuppetLint::Data.class_indexes
   end
 
+  # Public: Provides positional information for any defined type definitions in
+  # the tokens array to the check plugins.
+  #
+  # Returns an Array of Hashes containing the position information.
   def defined_type_indexes
     PuppetLint::Data.defined_type_indexes
   end
 
+  # Public: Provides the expanded path of the file being analysed to check
+  # plugins.
+  #
+  # Returns the String path.
   def fullpath
     PuppetLint::Data.fullpath
   end
 
+  # Public: Provides the path of the file being analysed as it was provided to
+  # puppet-lint to the check plugins.
+  #
+  # Returns the String path.
   def path
     PuppetLint::Data.path
   end
 
+  # Public: Provides the name of the file being analysed to the check plugins.
+  #
+  # Returns the String file name.
   def filename
     PuppetLint::Data.filename
   end
 
+  # Public: Provides a list of formatting tokens to the check plugins.
+  #
+  # Returns an Array of Symbol token types.
   def formatting_tokens
     PuppetLint::Data.formatting_tokens
   end
 
+  # Public: Provides a list of manifest lines to the check plugins.
+  #
+  # Returns an Array of manifest lines.
   def manifest_lines
     PuppetLint::Data.manifest_lines
   end
 
+  # Internal: Prepare default problem report information.
+  #
+  # Returns a Hash of default problem information.
   def default_info
     @default_info ||= {
       :check      => self.class.const_get('NAME'),

lib/puppet-lint/checks.rb

@@ -1,5 +1,7 @@
 require 'puppet-lint/checkplugin'
 
+# Internal: Various methods that orchestrate the actions of the puppet-lint
+# check plugins.
 class PuppetLint::Checks
   # Public: Get an Array of problem Hashes.
   attr_accessor :problems
@@ -80,6 +82,9 @@ def enabled_checks
     end.call
   end
 
+  # Internal: Render the fixed manifest.
+  #
+  # Returns the manifest as a String.
   def manifest
     PuppetLint::Data.tokens.map { |t| t.to_manifest }.join('')
   end

lib/puppet-lint/configuration.rb

@@ -1,4 +1,6 @@
 class PuppetLint
+  # Public: A singleton class to store the running configuration of
+  # puppet-lint.
   class Configuration
     # Internal: Add helper methods for a new check to the
     # PuppetLint::Configuration object.

lib/puppet-lint/data.rb

@@ -1,6 +1,8 @@
 require 'singleton'
 require 'set'
 
+# Public: A singleton class storing all the information about the manifest
+# being analysed.
 class PuppetLint::Data
   include Singleton
 
@@ -12,6 +14,11 @@ class << self
     # Internal: Get/Set the raw manifest data, split by \n.
     attr_accessor :manifest_lines
 
+    # Internal: Store the tokenised manifest.
+    #
+    # tokens - The Array of PuppetLint::Lexer::Token objects to store.
+    #
+    # Returns nothing.
     def tokens=(tokens)
       @tokens = tokens
       @title_tokens = nil
@@ -20,6 +27,9 @@ def tokens=(tokens)
       @defined_type_indexes = nil
     end
 
+    # Public: Get the tokenised manifest.
+    #
+    # Returns an Array of PuppetLint::Lexer::Token objects.
     def tokens
       if caller[0][/`.*'/][1..-2] == 'check'
         @tokens.dup
@@ -28,6 +38,12 @@ def tokens
       end
     end
 
+    # Internal: Store the path to the manifest file and populate fullpath and
+    # filename.
+    #
+    # val - The path to the file as a String.
+    #
+    # Returns nothing.
     def path=(val)
       @path = val
       if val.nil?
@@ -216,6 +232,14 @@ def definition_indexes(type)
       result
     end
 
+    # Internal: Finds all the tokens that make up the defined type or class
+    # definition parameters.
+    #
+    # these_tokens - An Array of PuppetLint::Lexer::Token objects that make up
+    #                the defined type or class definition.
+    #
+    # Returns an Array of PuppetLint::Lexer::Token objects or nil if it takes
+    # no parameters.
     def param_tokens(these_tokens)
       depth = 0
       lparen_idx = nil

lib/puppet-lint/lexer.rb

@@ -4,6 +4,8 @@
 require 'set'
 
 class PuppetLint
+  # Internal: A generic error thrown by the lexer when it encounters something
+  # it can't handle.
   class LexerError < StandardError
     # Internal: Get the Integer line number of the location of the error.
     attr_reader :line_no
@@ -28,6 +30,8 @@ def initialize(code, offset)
     end
   end
 
+  # Internal: The puppet-lint lexer. Converts your manifest into its tokenised
+  # form.
   class Lexer
     # Internal: A Hash whose keys are Strings representing reserved keywords in
     # the Puppet DSL.

lib/puppet-lint/lexer/token.rb

@@ -1,5 +1,7 @@
 class PuppetLint
   class Lexer
+    # Public: Stores a fragment of the manifest and the information about its
+    # location in the manifest.
     class Token
       # Public: Returns the Symbol type of the Token.
       attr_accessor :type

lib/puppet-lint/monkeypatches/string_prepend.rb

@@ -1,5 +1,11 @@
 unless String.respond_to?('prepend')
+  # Internal: Monkey patching String.
   class String
+    # Internal: Prepends a String to self.
+    #
+    # lead - The String to prepend self with.
+    #
+    # Returns a String which is lead and self concatenated.
     def prepend(lead)
       self.replace "#{lead}#{self}"
     end

lib/puppet-lint/optparser.rb

@@ -1,5 +1,7 @@
 require 'optparse'
 
+# Public: Contains the puppet-lint option parser so that it can be used easily
+# in multiple places.
 class PuppetLint::OptParser
   HELP_TEXT = <<-EOF
     puppet-lint
@@ -12,6 +14,9 @@ class PuppetLint::OptParser
     Option:
   EOF
 
+  # Public: Initialise a new puppet-lint OptionParser.
+  #
+  # Returns an OptionParser object.
   def self.build
     OptionParser.new do |opts|
       opts.banner = HELP_TEXT

lib/puppet-lint/plugins.rb

@@ -1,6 +1,11 @@
 require 'pathname'
 
 class PuppetLint
+  # Public: Various methods that implement puppet-lint's plugin system
+  #
+  # Examples
+  #
+  #   PuppetLint::Plugins.load_spec_helper
   class Plugins
     # Internal: Find any gems containing puppet-lint plugins and load them.
     #

lib/puppet-lint/tasks/puppet-lint.rb

@@ -4,7 +4,20 @@
 require 'rake/tasklib'
 
 class PuppetLint
+  # Public: A Rake task that can be loaded and used with everything you need.
+  #
+  # Examples
+  #
+  #   require 'puppet-lint'
+  #   PuppetLint::RakeTask.new
   class RakeTask < ::Rake::TaskLib
+    # Public: Initialise a new PuppetLint::RakeTask.
+    #
+    # args - Not used.
+    #
+    # Example
+    #
+    #   PuppetLint::RakeTask.new
     def initialize(*args)
       desc 'Run puppet-lint'