made yardoc not holler at me

.yardopts

@@ -1,5 +1,10 @@
+--readme   README.md
+--markup   markdown
+--charset  UTF-8
+-
 VERSION
 CHANGELOG.md
 LICENSE.md
 README.md
-notes/*
+notes/*.md
+notes/*.txt

Gemfile

@@ -11,14 +11,17 @@ group :development do
   gem 'rspec',       "~> 2.5"
   gem 'yard',        "~> 0.6"
   gem 'redcarpet',   "~> 2"
-  gem 'configliere', "~> 0.4.8"
 end
 
 group :test do
   gem 'spork',       ">= 0.9.0", :platform => :mri
   gem 'rcov',        ">= 0.9.9", :platform => :ruby_18
   gem 'simplecov',   ">= 0.5",   :platform => :ruby_19
-  gem 'watchr',      "~> 0.7"
+  #
+  gem 'ruby_gntp'
+  gem 'guard',         "~> 1"
+  gem 'guard-rspec'
+  gem 'guard-yard'
 end
 
 group :support do

Guardfile

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+
+# More info at https://github.com/guard/guard#readme
+
+guard 'yard' do
+  watch(%r{lib/.+\.rb})
+  watch(%r{notes/.+\.(md|txt)}) { "notes" }
+end
+

README.md

@@ -13,29 +13,30 @@ This repo implements:
 
 To jump right into using Ironfan, follow our [Installation Instructions](https://github.com/infochimps-labs/ironfan/wiki/INSTALL). For an explanatory tour, check out our [Hadoop Walkthrough](https://github.com/infochimps-labs/ironfan/wiki/INSTALL).  Please file all issues on [Ironfan issues](https://github.com/infochimps-labs/ironfan/issues).
 
-## Index
+### Tools
 
-The full Ironfan toolset:
+Ironfan consists of the following Toolset:
 
-###Core Tools:
+* [ironfan-homebase](https://github.com/infochimps-labs/ironfan-homebase): centralizes the cookbooks, roles and clusters. A solid foundation for any chef user.
+* [ironfan gem](https://github.com/infochimps-labs/ironfan):
+  - core models to describe your system diagram with a clean, expressive domain-specific language
+  - knife plugins to orchestrate clusters of machines using simple commands like `knife cluster launch`
+  - logic to coordinate truth among chef server and cloud providers.
+* [ironfan-pantry](https://github.com/infochimps-labs/ironfan-pantry): Our collection of industrial-strength, cloud-ready recipes for Hadoop, HBase, Cassandra, Elasticsearch, Zabbix and more.
+* [silverware cookbook](https://github.com/infochimps-labs/ironfan-homebase/tree/master/cookbooks/silverware): coordinate discovery of services ("list all the machines for `awesome_webapp`, that I might load balance them") and aspects ("list all components that write logs, that I might logrotate them, or that I might monitor the free space on their volumes".
 
-* [ironfan-homebase](https://github.com/infochimps-labs/ironfan-homebase): Centralizes the cookbooks, roles and clusters. A solid foundation for any Chef user.
-* [ironfan gem](https://github.com/infochimps-labs/ironfan): The core Ironfan models, and Knife plugins to orchestrate machines and coordinate truth among your homebase, cloud and chef server. It comes with [ironfan-homebase](https://github.com/infochimps-labs/ironfan-homebase).
-* [ironfan-pantry](https://github.com/infochimps-labs/ironfan-pantry): Our collection of industrial-strength, cloud-ready recipes for Hadoop, HBase, Cassandra, Elasticsearch, Zabbix and more. 
-* [silverware cookbook](https://github.com/infochimps-labs/ironfan-pantry/tree/master/cookbooks/silverware): Helps you coordinate discovery of services ("list all the machines for `awesome_webapp`, that I might load balance them") and aspects ("list all components that write logs, that I might logrotate them, or that I might monitor the free space on their volumes"). Found within the [ironfan-pantry](https://github.com/infochimps-labs/ironfan-pantry).
-
-###Core Documentation:
-
-* [ironfan wiki](https://github.com/infochimps-labs/ironfan/wiki): High-level documentation and install instructions.
-* [ironfan issues](https://github.com/infochimps-labs/ironfan/issues): Bugs or questions and feature requests for *any* part of the Ironfan toolset.
-* [ironfan gem docs](http://rdoc.info/gems/ironfan): Rdoc docs for Ironfan.
-
-## What is Ironfan? 
-Ironfan is a systems provisioning and deployment tool. Ironfan automates not only machine configuration, but entire systems configuration to enable the entire Big Data stack, including tools for _data ingestion_, _scraping_, _storage_, _computation_, and _monitoring_.  
-
-Ironfan builds on Chef, but is opinionated about its architecture, which allows broader integration between components. It assumes a source repository, a central Chef Server, and a modern POSIX-compliant operating system for a base image. Currently, it works best with Git, Amazon Web Services, Ubuntu 11.04, with exploration into other virtualization platforms (Vagrant, etc.) and operating systems (Centos, FreeSBD, etc) ongoing, both inside and outside of Infochimps.
-
-To understand the Philosophy behind how we use Chef go [here](https://github.com/infochimps-labs/ironfan/wiki/Philosophy).
+### Documentation
 
+* [ironfan wiki](https://github.com/infochimps-labs/ironfan/wiki): high-level documentation and install instructions
+* [Index of wiki pages](https://github.com/infochimps-labs/ironfan/wiki/_pages)
+* [ironfan issues](https://github.com/infochimps-labs/ironfan/issues): bugs, questions and feature requests for *any* part of the ironfan toolset.
+* [ironfan gem docs](http://rdoc.info/gems/ironfan): rdoc docs for ironfan
+* Ironfan powers the [Infochimps Platform](http://www.infochimps.com/how-it-works), our scalable enterprise big data platform. Ironfan Enterprise adds zero-configuration logging, monitoring and a compelling UI.
+* [Ironfan Screencast](http://bit.ly/ironfan-hadoop-in-20-minutes) -- build a Hadoop cluster from scratch in 20 minutes.
 
+### The Ironfan Way
 
+* [Core Concepts](core_concepts)     -- Components, Announcements, Amenities and more.
+* [Philosophy](philosophy)            -- best practices and lessons learned
+* [Style Guide](style_guide)         -- common attribute names, how and when to include other cookbooks, and more
+* [Homebase Layout](homebase-layout) -- how this homebase is organized, and why

lib/ironfan/cloud.rb

@@ -57,7 +57,7 @@ def initialize(owner, *args)
       end
 
       # default values to apply where no value was set
-      # @returns [Hash] hash of defaults
+      # @return [Hash] hash of defaults
       def defaults
         reverse_merge!({
           :image_name         => 'natty',

lib/ironfan/dsl_object.rb

@@ -54,7 +54,7 @@ def initialize(attrs={}, &block)
     #
     # Defines DSL attributes
     #
-    # @params [Array(String)] key_names DSL attribute names
+    # @param [Array(String)] key_names DSL attribute names
     #
     # @example
     #   class Mom < Ironfan::DslObject

lib/ironfan/server_slice.rb

@@ -236,7 +236,7 @@ def joined_names
     #
     # @yield each server, in turn
     #
-    # @return array (in same order as servers) of each block's result
+    # @return [Array] array (in same order as servers) of each block's result
     def parallelize
       servers.map do |svr|
         sleep(0.1) # avoid hammering with simultaneous requests
@@ -251,7 +251,7 @@ def parallelize
     # @param [Symbol]  method   -- method to call on each server
     # @param [Boolean] threaded -- execute each call in own thread
     #
-    # @return array (in same order as servers) of results for that method
+    # @return [Array] array (in same order as servers) of results for that method
     def delegate_to_servers method, threaded = true
       if threaded  # Call in threads
         threads = parallelize{|svr| svr.send(method) }