more rdoc tweaks, use sdoc, and gitignore the rdoc directory

.gitignore

@@ -12,6 +12,7 @@ chef-server/pkg
 chef-server-webui/pkg
 chef-server-api/pkg
 chef/log
+chef/rdoc
 chef-server/log
 chef-solr/chef-solr.gemspec
 log

chef/Rakefile

@@ -63,8 +63,19 @@ Rake::GemPackageTask.new(spec) do |pkg|
   pkg.gem_spec = spec
 end
 
-Rake::RDocTask.new do |rd|
-  rd.rdoc_files.include("lib/**/*.rb")
+begin
+  require 'sdoc'
+
+  Rake::RDocTask.new do |rdoc|
+    rdoc.title = "Chef Ruby API Documentation"
+    rdoc.main = "README.rdoc"
+    rdoc.options << '--fmt' << 'shtml' # explictly set shtml generator
+    rdoc.template = 'direct' # lighter template
+    rdoc.rdoc_files.include("README.rdoc", "LICENSE", "spec/tiny_server.rb", "lib/**/*.rb")
+    rdoc.rdoc_dir = "rdoc"
+  end
+rescue LoadError
+  puts "sdoc is not available. (sudo) gem install sdoc to generate rdoc documentation."
 end
 
 task :install => :package do

chef/lib/chef/cookbook/cookbook_collection.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Tim Hinderliter (<tim@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.

chef/lib/chef/cookbook/file_system_file_vendor.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Author:: Tim Hinderliter (<tim@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.

chef/lib/chef/mixin/recipe_definition_dsl_core.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Copyright:: Copyright (c) 2008, 2009 Opscode, Inc.
@@ -21,6 +21,7 @@
 require 'chef/mixin/convert_to_class_name'
 require 'chef/mixin/language'
 
+#--
 # UGH. this is a circular require that will cause an uninitialized constant
 # error, but this file really does depend on Chef::Recipe. oh well.
 # require 'chef/recipe'

chef/lib/chef/mixin/shell_out.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0

chef/lib/chef/mixin/template.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Copyright:: Copyright (c) 2008 Opscode, Inc.
 # License:: Apache License, Version 2.0

chef/lib/chef/mixin/xml_escape.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2009 Opscode, Inc.
 # Copyright:: Copyright (c) 2005 Sam Ruby
@@ -16,7 +16,7 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-#
+#--
 # Portions of this code are adapted from Sam Ruby's xchar.rb
 # http://intertwingly.net/stories/2005/09/28/xchar.rb 
 #

chef/lib/chef/monkey_patches/string.rb

@@ -17,7 +17,7 @@
 #
 
 # == String (Patch)
-# On ruby 1.9, Strings are aware of multibyte characters, so #size and length
+# On ruby 1.9, Strings are aware of multibyte characters, so +size+ and +length+
 # give the actual number of characters. In Chef::REST, we need the bytesize
 # so we can correctly set the Content-Length headers, but ruby 1.8.6 and lower
 # don't define String#bytesize. Monkey patching time!

chef/lib/chef/provider/template.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2008, 2010 Opscode, Inc.
@@ -22,20 +22,13 @@
 require 'chef/mixin/checksum'
 require 'chef/file_access_control'
 
-#require 'chef/mixin/find_preferred_file'
-#require 'chef/rest'
-#require 'chef/file_cache'
-#require 'uri'
-#require 'tempfile'
-
 class Chef
   class Provider
 
     class Template < Chef::Provider::File
 
       include Chef::Mixin::Checksum
       include Chef::Mixin::Template
-      #include Chef::Mixin::FindPreferredFile
 
       def load_current_resource
         super
@@ -98,101 +91,15 @@ def set_all_access_controls(file)
         @new_resource.updated = access_controls.modified?
       end
 
-      # def locate_or_fetch_template
-      #   Chef::Log.debug("looking for template #{@new_resource.source} in cookbook #{cookbook_name.inspect}")
-      # 
-      #   cache_file_name = "cookbooks/#{cookbook_name}/templates/default/#{@new_resource.source}"
-      #   template_cache_name = "#{cookbook_name}_#{@new_resource.source}"
-      # 
-      #   if @new_resource.local
-      #     cache_file_name = @new_resource.source
-      #   elsif Chef::Config[:solo]
-      #     cache_file_name = solo_cache_file_name
-      #   else
-      #     raw_template_file = fetch_template_via_rest(cache_file_name, template_cache_name)
-      #   end
-      # 
-      #   if template_updated?
-      #     Chef::Log.debug("Updating template for #{@new_resource} in the cache")
-      #     Chef::FileCache.move_to(raw_template_file.path, cache_file_name)
-      #   end
-      #   cache_file_name
-      # end
-
       private
 
-      # def template_updated
-      #   @template_updated = true
-      # end
-      # 
-      # def template_not_updated
-      #   @template_updated = false
-      # end
-      # 
-      # def template_updated?
-      #   @template_updated
-      # end
-      # 
-      # def cookbook_name
-      #   @cookbook_name = (@new_resource.cookbook || @new_resource.cookbook_name)
-      # end
-
       def render_with_context(template_location, &block)
         context = {}
         context.merge!(@new_resource.variables)
         context[:node] = node
         render_template(IO.read(template_location), context, &block)
       end
 
-      # def solo_cache_file_name
-      #   filename = find_preferred_file(
-      #     cookbook_name,
-      #     :template,
-      #     @new_resource.source,
-      #     node[:fqdn],
-      #     node[:platform],
-      #     node[:platform_version]
-      #   )
-      #   Chef::Log.debug("Using local file for template:#{filename}")
-      #   Pathname.new(filename).relative_path_from(Pathname.new(Chef::Config[:file_cache_path])).to_s
-      # end
-      # 
-      # def fetch_template_via_rest(cache_file_name, template_cache_name)
-      #   if node.run_state[:template_cache].has_key?(template_cache_name)
-      #     Chef::Log.debug("I have already fetched the template for #{@new_resource} once this run, not checking again.")
-      #     template_not_updated
-      #     return false
-      #   end
-      # 
-      #   r = Chef::REST.new(Chef::Config[:template_url])
-      # 
-      #   current_checksum = nil
-      # 
-      #   if Chef::FileCache.has_key?(cache_file_name)
-      #     current_checksum = self.checksum(Chef::FileCache.load(cache_file_name, false))
-      #   else
-      #     Chef::Log.debug("Template #{@new_resource} is not in the template cache")
-      #   end
-      # 
-      #   template_url = generate_url(@new_resource.source, "templates", :checksum => current_checksum)
-      # 
-      #   begin
-      #     raw_template_file = r.get_rest(template_url, true)
-      #     template_updated
-      #   rescue Net::HTTPRetriableError
-      #     if e.response.kind_of?(Net::HTTPNotModified)
-      #       Chef::Log.debug("Cached template for #{@new_resource} is unchanged")
-      #     else
-      #       raise
-      #     end
-      #   end
-      # 
-      #   # We have checked the cache for this template this run
-      #   node.run_state[:template_cache][template_cache_name] = true
-      # 
-      #   raw_template_file
-      # end
-
     end
   end
 end

chef/lib/chef/recipe.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Copyright:: Copyright (c) 2008, 2009 Opscode, Inc.
@@ -26,6 +26,8 @@
 require 'chef/mixin/deprecation'
 
 class Chef
+  # == Chef::Recipe
+  # A Recipe object is the context in which Chef recipes are evaluated.
   class Recipe
 
     include Chef::Mixin::FromFile
@@ -42,6 +44,8 @@ class Recipe
     # For example:
     #   "aws::elastic_ip" returns [:aws, "elastic_ip"]
     #   "aws" returns [:aws, "default"]
+    #--
+    # TODO: Duplicates functionality of RunListItem
     def self.parse_recipe_name(recipe_name)
       rmatch = recipe_name.match(/(.+?)::(.+)/)
       if rmatch
@@ -65,10 +69,10 @@ def node
       run_context.node
     end
 
+    # Used by the DSL to look up resources when executing in the context of a
+    # recipe.
+    #--
     # what does this do? and what is args? TODO 5-14-2010.
-    #
-    # We believe this is used by the DSL when it's executing in the
-    # context of a recipe in order to look up resources.
     def resources(*args)
       run_context.resource_collection.find(*args)
     end
@@ -83,9 +87,9 @@ def resources(*args)
     #
     # === Returns
     # tags<Array>:: The contents of run_context.node[:tags]
-    def tag(*args)
-      if args.length > 0
-        args.each do |tag|
+    def tag(*tags)
+      if tags.length > 0
+        tags.each do |tag|
           run_context.node[:tags] << tag unless run_context.node[:tags].include?(tag)
         end
         run_context.node[:tags]
@@ -94,16 +98,16 @@ def tag(*args)
       end
     end
 
-    # Returns true if the node is tagged with the supplied list of tags.
+    # Returns true if the node is tagged with *all* of the supplied +tags+.
     #
     # === Parameters
     # tags<Array>:: A list of tags
     #
     # === Returns
     # true<TrueClass>:: If all the parameters are present
     # false<FalseClass>:: If any of the parameters are missing
-    def tagged?(*args)
-      args.each do |tag|
+    def tagged?(*tags)
+      tags.each do |tag|
         return false unless run_context.node[:tags].include?(tag)
       end
       true
@@ -116,8 +120,8 @@ def tagged?(*args)
     #
     # === Returns
     # tags<Array>:: The current list of run_context.node[:tags]
-    def untag(*args)
-      args.each do |tag|
+    def untag(*tags)
+      tags.each do |tag|
         run_context.node[:tags].delete(tag)
       end
     end

chef/lib/chef/rest.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Thom May (<thom@clearairturbulence.org>)
 # Author:: Nuo Yan (<nuo@opscode.com>)
@@ -37,6 +37,10 @@ class REST
     attr_reader :auth_credentials
     attr_accessor :url, :cookies, :sign_on_redirect, :redirect_limit
 
+    # Create a REST client object. The supplied +url+ is used as the base for
+    # all subsequent requests. For example, when initialized with a base url
+    # http://localhost:4000, a call to +get_rest+ with 'nodes' will make an
+    # HTTP GET request to http://localhost:4000/nodes
     def initialize(url, client_name=Chef::Config[:node_name], signing_key_filename=Chef::Config[:client_key], options={})
       @url = url
       @cookies = CookieJar.instance
@@ -93,7 +97,7 @@ def register(name=Chef::Config[:node_name], destination=Chef::Config[:client_key
 
     # Send an HTTP GET request to the path
     #
-    # Using this method to #fetch a file is considered deprecated.
+    # Using this method to +fetch+ a file is considered deprecated.
     #
     # === Parameters
     # path:: The path to GET

chef/lib/chef/runner.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Adam Jacob (<adam@opscode.com>)
 # Author:: Christopher Walters (<cw@opscode.com>)
 # Author:: Tim Hinderliter (<tim@opscode.com>)

chef/lib/chef/shell_out.rb

@@ -1,4 +1,4 @@
-#
+#--
 # Author:: Daniel DeLeo (<dan@opscode.com>)
 # Copyright:: Copyright (c) 2010 Opscode, Inc.
 # License:: Apache License, Version 2.0