buildr 1.3.5-java → 1.4.0-java

data/doc/contributing.textile

@@ -250,3 +250,8 @@ A test-infected developer since 2001, Lacton yearns for a development infrastruc
 *"Daniel Spiewak":http://www.codecommit.com/blog* (djspiewak at apache.org)
 
 Daniel originally came to Buildr in search of a Scala build tool which was better than Ant.  He got more than he bargained for.  Now, he works to advance Buildr as the absolute best tool for supporting Scala development.
+
+*"Antoine Toulme":http://www.lunar-ocean.com/* (toulmean at apache.org)
+
+Antoine used Buildr first as an excuse to evade in Ruby land, creating plugins for Debian packaging, GWT compilation, or the NSIS installer. His main area of interest is the resolving of dependencies in the OSGi world. He works on making Buildr a standalone rock solid tool.
+

data/doc/download.textile

@@ -20,15 +20,26 @@ The source code is included in both source and binary distribution, the Gem dist
 
 h2(#dist).  Binaries and Source Code
 
+h3. buildr 1.3.5 (2009-10-05)
+
+|_. Package |_. MD5 Checksum |_. PGP |
+| "buildr-1.3.5.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.gem | "5a04d8593f98606f15dd589988afe24d":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.gem.asc |
+| "buildr-1.3.5-java.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5-java.gem | "d930c851196cd8f9ea66b7190d324dd4":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-java.gem.asc |
+| "buildr-1.3.5-x86-mswin32.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem | "a6dfc07b4c22e1902de6269e5776a32c":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5-x86-mswin32.gem.asc |
+| "buildr-1.3.5.tgz":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.tgz | "d246b84d70a5934536a3f0cd8de1abf7":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.tgz.asc |
+| "buildr-1.3.5.zip":http://www.apache.org/dyn/closer.cgi/buildr/1.3.5/buildr-1.3.5.zip | "d05f9a24f488318d22964bd2f443a76c":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.5/buildr-1.3.5.zip.asc |
+
+p>. ("Release signing keys":http://www.apache.org/dist/buildr/1.3.5/KEYS)
+
 h3. buildr 1.3.4 (2009-04-21)
 
 |_. Package |_. MD5 Checksum |_. PGP |
-| "buildr-1.3.4.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem | "34247286f910be1724f63b9e795e75ed":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.asc |
-| "buildr-1.3.4-java.gem":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem | "44ed67bf835cf2abdc2b6723b5eceadb":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.asc |
-| "buildr-1.3.4.tgz":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz | "7d918b88a3bb8139f28f6ff0b39d003c":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.asc |
-| "buildr-1.3.4.zip":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip | "8f4cf84dc6e293aac5fba7e2a9cc0776":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.asc |
+| "buildr-1.3.4.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.gem | "34247286f910be1724f63b9e795e75ed":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.gem.asc |
+| "buildr-1.3.4-java.gem":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4-java.gem | "44ed67bf835cf2abdc2b6723b5eceadb":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4-java.gem.asc |
+| "buildr-1.3.4.tgz":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.tgz | "7d918b88a3bb8139f28f6ff0b39d003c":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.tgz.asc |
+| "buildr-1.3.4.zip":http://www.apache.org/dyn/closer.cgi/buildr/1.3.4/buildr-1.3.4.zip | "8f4cf84dc6e293aac5fba7e2a9cc0776":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.md5 | "Sig":http://www.apache.org/dist/buildr/1.3.4/buildr-1.3.4.zip.asc |
 
-p>. ("Release signing keys":http://www.apache.org/dist/buildr/1.3.4/KEYS)
+p>. ("Release signing keys":http://www.apache.org/dist/buildr/KEYS)
 
 
 h3. buildr 1.3.3-incubating (2008-10-08)

data/doc/extending.textile

@@ -16,7 +16,7 @@ file('derby.sql') do
   REQUIRES = [
     'org.apache.openjpa:openjpa-all:jar:0.9.7-incubating',
     'commons-collections:commons-collections:jar:3.1',
-    . . . 
+    . . .
     'net.sourceforge.serp:serp:jar:1.11.0' ]
   ant('openjpa') do |ant|
     ant.taskdef :name=>'mapping',
@@ -48,20 +48,20 @@ But just using functions is not always enough.  You end up with a Buildfile cont
 
 If you want to share these pre-canned definitions between projects, you have a few more options.  You can share the @tasks@ directory using SVN externals, Git modules, or whichever cross-repository feature your source control system supports. Another mechanism with better version control is to package all these tasks, functions and modules into a "Gem":http://rubygems.org/ and require it from your Buildfile.  You can run your own internal Gem server for that.
 
-To summarize, there are several common ways to distribute extensions: 
+To summarize, there are several common ways to distribute extensions:
 * Put them in the same place (e.g. @~/.buildr@) and require them from your
 @buildfile@
 * Put them directly in the project, typically under the @tasks@ directory.
 * Put them in a shared code repository, and link to them from your project's @tasks@ directory
 * As Ruby gems and specify which gems are used in the settings file
 
-You can also get creative and devise your own way to distribute extensions.  
+You can also get creative and devise your own way to distribute extensions.
 "Sake":http://errtheblog.com/post/6069 is a good example of such initiative that lets you deploy Rake tasks on a system-wide basis.
 
 h2(#extensions).  Creating Extensions
 
 The basic mechanism for extending projects in Buildr are Ruby modules.  In fact, base features like compiling and testing are all developed in the form of modules, and then added to the core Project class.
-  
+
 A module defines instance methods that are then mixed into the project and become instance methods of the project.  There are two general ways for extending projects.  You can extend all projects by including the module in Project:
 
 {% highlight ruby %}
@@ -91,6 +91,7 @@ This example illustrates how to write a simple extension:
 
 {% highlight ruby %}
 module LinesOfCode
+
   include Extension
 
   first_time do
@@ -101,33 +102,58 @@ module LinesOfCode
 
   before_define do |project|
     # Define the loc task for this particular project.
-    define_task 'loc' do |task|
-      lines = task.prerequisites.map { |path| Dir["#{path}/**/*"] }.flatten.uniq.
-        inject(0) { |total, file| total + File.readlines(file).count }
+    project.recursive_task 'loc' do |task|
+      lines = task.prerequisites.map { |path|
+        Dir["#{path}/**/*"]
+      }.flatten.uniq.inject(0) { |total, file|
+        total = 0 if total.nil?
+        if File.file? file then
+          total + File.readlines(file).count
+        end
+      }
       puts "Project #{project.name} has #{lines} lines of code"
-    end
+      end
   end
 
   after_define do |project|
     # Now that we know all the source directories, add them.
-    task('loc'=>compile.sources + compile.test.sources)
+    task('loc' => project.compile.sources + project.test.sources)
   end
 
   # To use this method in your project:
-  #   loc path_1, path_2
+  # loc path_1, path_2
   def loc(*paths)
-    task('loc'=>paths)
+    task('loc' => paths)
   end
 
 end
 
 class Buildr::Project
-  include LinesOfCode
+    include LinesOfCode
 end
 {% endhighlight %}
 
 You may find interesting that this Extension API is used pervasively inside Buildr itself.  Many of the standard tasks such as @compile@, @test@, @package@  are extensions to a very small core.
 
+Starting with Buildr 1.4, it's possible to define ordering between @before_define@ and @after_define@ code blocks in a way similar to Rake's dependencies.  For example, if you wanted to override @project.test.compile.from@ in @after_define@, you could do so by in
+
+{% highlight ruby %}
+after_define(:functional_tests) do |project|
+  # Change project.test.compile.from if it's not already pointing
+  # to a location with Java sources
+  if Dir["#{project.test.compile.from}/**/*.java"].size == 0 &&
+     Dir["#{project._(:src, 'test-functional', :java)}/**/*.java"].size > 0
+    project.test.compile.from project._(:src, 'test-functional', :java)
+  end
+end
+
+# make sure project.test.compile.from is updated before the
+# compile extension picks up its value
+after_define(:compile => :functional_test)
+{% endhighlight %}
+
+Core extensions provide the following named callbacks: @compile@, @test@, @build@, @package@ and @check@.
+
 h2(#layouts).  Using Alternative Layouts
 
 Buildr follows a common convention for project layouts: Java source files appear in @src/main/java@ and compile to @target/classes@, resources are copied over from @src/main/resources@ and so forth.  Not all projects follow this convention, so it's now possible to specify an alternative project layout.

data/doc/installing.textile

@@ -38,7 +38,7 @@ $ sudo gem update --system
 On *Ubuntu* you have to install several packages:
 
 {% highlight sh %}
-$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential 
+$ sudo apt-get install ruby-full ruby1.8-dev libopenssl-ruby build-essential
 {% endhighlight %}
 
 The Debian package for @rubygems@ will not allow you to install Buildr, so you need to install RubyGems from source:
@@ -70,6 +70,8 @@ h2(#osx).  Installing on OS X
 
 *The easy way:* Use this script to "install Buildr on OS X":scripts/install-osx.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  It will also install Ruby 1.8.6 if not already installed (using MacPorts/Fink) and upgrage RubyGems to 1.3.1 or later.
 
+You need to have the Apple Development Tools installed.  They are available on the Mac OSX installation CD.
+
 <br>
 
 *In details:* OS X 10.5 (Leopard) comes with a recent version of Ruby 1.8.6.  You do not need to install a different version of Ruby when running OS X 10.5.
@@ -104,7 +106,7 @@ $ sudo env JAVA_HOME=$JAVA_HOME gem install buildr -v 1.3.4
 
 h2(#windows).  Installing on Windows
 
-*The easy way:*  The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.  Once installed, set the @JAVA_HOME@ environment variable and run @gem install buildr@.
+*The easy way:*  The easiest way to install Ruby is using the "one-click installer":http://rubyinstaller.rubyforge.org/.  Be sure to install Ruby 1.8.6; support for Ruby 1.9.x is still a work in progress.  Once installed, set the @JAVA_HOME@ environment variable and run @gem install buildr --platform mswin32@.
 
 <br>
 
@@ -117,17 +119,16 @@ h2(#windows).  Installing on Windows
 Before installing Buildr, please set the @JAVA_HOME@ environment variable to point to your JDK distribution.  Next, use Ruby Gem to install Buildr:
 
 {% highlight sh %}
-> gem install buildr
+> gem install buildr --platform mswin32
 {% endhighlight %}
 
 To upgrade to a new version or install a specific version:
 
 {% highlight sh %}
 > gem update buildr
-> gem install buildr -v 1.3.4
+> gem install buildr -v 1.3.4 --platform mswin32
 {% endhighlight %}
 
-
 h2(#jruby).  Installing for JRuby
 
 *The easy way:* Use this bash script to "install Buildr on JRuby":scripts/install-jruby.sh.  This script will install the most recent version of Buildr, or if already installed, upgrade to the most recent version.  If necessary, it will also install JRuby 1.1.6 in @/opt/jruby@ and update the @PATH@ variable in @~/.bash_profile@ or @~/.profile@.

data/doc/languages.textile

@@ -101,9 +101,9 @@ testng: 5.7
 {% endhighlight %}
 
 
-h4. JBehave 
+h4. JBehave
 
-"JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language. 
+"JBehave":http://jbehave.org/ is a pure Java BDD framework, stories and behaviour specifications are written in the Java language.
 
 To use JBehave in your project you can select it with @test.using :jbehave@.
 
@@ -126,51 +126,75 @@ jbehave: 1.0.1
 {% endhighlight %}
 
 
-h2(#scala). Scala
+h3. Documentation
 
-Before using Scala, you must first @require@ the Scala compiler:
+Buildr offers support for using JavaDoc to generate documentation from any Java sources in a project.  This is done using the @doc@ task:
 
-{% highlight ruby %}
-require 'buildr/scala'
+{% highlight sh %}
+$ buildr doc
 {% endhighlight %}
 
-By default, Buildr will attempt to use any version of Scala which is already
-installed on your system.  However, Buildr isn't *quite* smart enough to intuit
-such things on its own, so for most cases, it requires the @SCALA_HOME@
-environment variable to be set pointing to the root of the Scala installation
-(e.g. @/usr/local/scala-2.7.5.final@).  The only exception to this is if you have
-installed Scala via "MacPorts":http://www.macports.org/  Buildr will look in the
-@/opt/local/share/scala/@ directory *before* it uses the @SCALA_HOME@ envar.
+This will use the same @.java@ sources used by the @compile@ task to produce JavaDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
 
-However, if @SCALA_HOME@ is not set, or if it points to an invalid Scala
-installation, then Buildr has a fallback option.  The Scala compiler and standard
-library are both available from the "Scala Tools repository":http://scala-tools.org/.
-If no other Scala installation can be found, Buildr will download the appropriate
-artifacts and use them instead of a full install.  The only drawback to this
-approach is the FSC compiler is *not* available when Scala has been downloaded
-in this fashion.
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
 
-When Scala is downloaded from the Maven2 repository, Buildr will attempt to use
-the very latest version (starting from version 2.7.5).  If you wish to override
-this default, you will need to make use of the @artifact_ns@ construct *before*
-you @require@ Scala support in your buildfile:
+The @doc@ task supports any option that the @javadoc@ command does (e.g. @-windowtitle@).  To pass an option to the JavaDoc generator, simply specify it using the @doc@ method:
 
 {% highlight ruby %}
-artifact_ns['Buildr::Compiler::Scalac'].library = '2.7.5'
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+
+h2(#scala). Scala
+
+Before using Scala, you must first @require@ the Scala compiler:
 
+{% highlight ruby %}
 require 'buildr/scala'
 {% endhighlight %}
 
-This snippet tells Buildr to use exactly version 2.7.5 of Scala when it downloads
-the JARs from Scala-Tools, regardless of what the latest version may be.
+By default, Buildr will attempt to use the latest stable release of Scala, which is currently Scala 2.7.7 as of April 2010.  Of course you can configure a specific version of Scala for your project by adding the following entry in @build.yaml@:
+
+{% highlight yaml %}
+scala.version: 2.8.0.Beta1  # Pick your version
+{% endhighlight %}
+
+Or, you can do the same programmatically:
 
-Regardless of how Scala has been obtained, you may determine the version in use
-by querying the @Scala.version@ attribute:
+{% highlight yaml %}
+# Must be placed before require 'buildr/scala'
+Buildr.settings.build['scala.version'] = "2.8.0.Beta1"
+{% endhighlight %}
+
+You may also determine the version in use by querying the @Scala.version@ attribute:
 
 {% highlight ruby %}
-Scala.version       # => '2.7.5'
+Scala.version       # => '2.7.7'
 {% endhighlight %}
 
+Regardless of how the Scala version is determined, if you have the same Scala version installed on your system and the SCALA_HOME environment variable points to it, then your local installation will be used.   Otherwise, Buildr will download it from the "Scala Tools repository":http://scala-tools.org/ which is automatically enlisted when you @require@ Scala.  The only drawback if you don't have a local installation is the FSC compiler won't be available.
+
+p(tip). For Mac users, if you have installed Scala via "MacPorts":http://www.macports.org/  Buildr will look in the
+@/opt/local/share/scala/@ directory if you have not set @SCALA_HOME@.
+
+
 h3. Compiling Scala
 
 The Scala compiler looks for source files in the project's @src/main/scala@  directory, and defaults to compiling them into the @target/classes@ directory.  It looks for test cases in the project's @src/test/scala@ and defaults to  compile them into the @target/test/classes@ directory.
@@ -190,6 +214,7 @@ The Scala compiler supports the following options:
 | @:deprecation@  | If true, shows deprecation messages.  False by default. |
 | @:optimise@     | Generates faster bytecode by applying optimisations to the program. |
 | @:other@        | Array of options passed to the compiler (e.g. @:other=>'-Xprint-types'@). |
+| @:make@         | Make strategy to be used by the compiler (e.g. @:make=>'transitive'@).  *Scala 2.8 only* |
 | @:target@       | Bytecode compatibility (e.g. '1.4'). |
 | @:warnings@     | Issue warnings when compiling.  True when running in verbose mode. |
 | @:javac@        | A hash of options passed to the @javac@ compiler verbatim. |
@@ -200,10 +225,41 @@ You may use @fsc@, the Fast Scala Compiler, which submits compilation jobs to a
 
 h4. Rebuild detection
 
-The Scala compiler task assumes that each @.scala@ source file generates a  corresponding @.class@ file under @target/classes@ (or @target/test/classses@  for tests). The source may generate more @.class@ files if it contains more than one class, object, trait or for anonymous functions and closures.
+The Scala 2.7 compiler task assumes that each @.scala@ source file generates a  corresponding @.class@ file under @target/classes@ (or @target/test/classses@  for tests). The source may generate more @.class@ files if it contains more than one class, object, trait or for anonymous functions and closures.
 
 For example, @src/main/scala/com/example/MyClass.scala@ should generate at least @target/classes/com/example/MyClass.class@. If that it not the case, Buildr will always recompile your sources because it will assume this is a new source file that has never been compiled before.
 
+Fortunately, Scala 2.8 provides a substantially better interface for implementing change detection.  Whenever you use Scala 2.8 (see below), Buildr will auto-detect the version and enable this feature dynamically.  After the @compile@ task runs, the relevant target directory will contain a @.scala-deps@ file, generated by the Scala compiler.  The manner in which this file is used can be configured using the @:make@ compiler option.  The following values are available:
+
+* @:all@ - Disables compiler-level change detection
+* @:changed@ - Only build changed files without considering file dependencies
+* @:immediate@ - *unknown*
+* @:transitive@ - Build changed files as well as their transitive file dependencies
+* @:transitivenocp@ - Build changed files as well as their transitive file dependencies (*default*)
+
+Please note that there are limits to compiler-level change detection.  Most notably, dependencies cannot be tracked across separate compilation targets.  This would cause problems in the case where an API has been changed in a main source file.  The test suite for the project will *not* be detected as requiring recompilation, potentially resulting in unexpected runtime exceptions.  When in doubt, run @clean@ to remove all dependency information.  In extreme cases, it is possible to completely disable compiler-level change detection by adding the following statement to your project definition:
+
+{% highlight ruby %}
+compile.using :make => :all
+{% endhighlight %}
+
+Effectively, this is telling the Scala compiler to ignore the information it has built up regarding source file dependencies.  When in this mode, only Buildr's change detection semantics remain in play (as described above).
+
+To avoid unusual behavior, compiler-level change detection is disabled whenever the joint Scala-Java compiler is used.  Thus, any @.java@ files in a project handled by the Scala compiler will cause the @:make@ option to be ignored and revert to the exclusive use of Buildr's change detection mechanism (as described above).
+
+h4. Scala 2.8
+
+As of version 1.4, Buildr has *non-default* support for Scala 2.8.  If your @SCALA_HOME@ environment variable is pointing to an installation of Scala 2.8, then Buildr will use that compiler and enable 2.8-specific features.
+
+As Scala 2.8 is currently pre-release, it is often desirable to maintain an installation of Scala 2.7 concurrently with Scala 2.8, defaulting to the former with the option to select the latter on a project-by-project basis.  This is most easily accomplished by setting @SCALA_HOME@ to point to the Scala 2.7 installation and @SCALA28_HOME@ to point to the Scala 2.8 installation.  With this configuration in place, Scala 2.8 can be selected for a specific project by dynamically reassigning @SCALA_HOME@ at the top of the buildfile (*before* @require 'buildr/scala'@):
+
+{% highlight ruby %}
+ENV['SCALA_HOME'] = ENV['SCALA28_HOME']
+
+require 'buildr/scala'
+...
+{% endhighlight %}
+
 h3. Testing with Scala
 
 Buildr supports two main Scala testing frameworks:   "ScalaTest":http://www.artima.com/scalatest and  "Specs":http://code.google.com/p/specs/.  "ScalaCheck":http://code.google.com/p/scalacheck/ is also supported within the confines of either of these two frameworks.  Thus, your Specs may use ScalaCheck properties, as may your ScalaTest suites.
@@ -236,17 +292,17 @@ import org.scalatest._
 
 class PropertyTestSuite extends FunSuite {
   var properties = Map[String, Any]()
-  
+
   test("testProperty") {
     assert(properties("name") === "value")
   }
 
-  protected override def runTests(testName: Option[String], 
-    reporter: Reporter, stopper: Stopper, includes: Set[String], 
+  protected override def runTests(testName: Option[String],
+    reporter: Reporter, stopper: Stopper, includes: Set[String],
     excludes: Set[String], properties: Map[String, Any])
   {
-    this.properties = properties;                              
-    super.runTests(testName, reporter, stopper, 
+    this.properties = properties;
+    super.runTests(testName, reporter, stopper,
                    includes, excludes, properties)
   }
 }
@@ -283,7 +339,7 @@ OBJENESIS = 'org.objenesis:objenesis:jar:1.1'
 
 define 'killer-app' do
   ...
-  
+
   test.with MOCKITO, CGLIB, ASM, OBJENESIS
 end
 {% endhighlight %}
@@ -316,6 +372,52 @@ class MySuite extends PropSuite {
 {% endhighlight %}
 
 
+h3. Documentation
+
+Buildr offers support for using ScalaDoc or VScalaDoc to generate documentation from any Scala sources in a project.  This is done using the @doc@ task:
+
+{% highlight sh %}
+$ buildr doc
+{% endhighlight %}
+
+This will use the same @.scala@ sources used by the @compile@ task to produce ScalaDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
+
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
+
+The @doc@ task supports any option that the @scaladoc@ command does (e.g. @-windowtitle@).  To pass an option to the ScalaDoc (or VScalaDoc) generator, simply specify it using the @doc@ method:
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+By default, the @doc@ task will use the ScalaDoc generator on Scala projects.  To select the VScalaDoc generator, you must use the @doc.using@ invocation:
+
+{% highlight ruby %}
+define 'foo' do
+  doc.using :vscaladoc
+end
+{% endhighlight %}
+
+The @doc@ task is *not* joint-compilation aware.  Thus, it will only generate ScalaDoc for mixed-source projects, it will not attempt to generate both JavaDoc and ScalaDoc.
+
+
 h2(#groovy). Groovy
 
 h3. Compiling Groovy
@@ -357,9 +459,9 @@ h3. Testing with Groovy
 
 h4. EasyB
 
-"EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/. 
+"EasyB":http://www.easyb.org/ is a BDD framework using "Groovy":http://groovy.codehaus.org/.
 
-Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy. 
+Specifications are written in the Groovy language, of course you get seamless Java integration as with all things groovy.
 
 To use this framework in your project you can select it with @test.using :easyb@.
 
@@ -378,6 +480,44 @@ Supports the following options:
 | @:format@       | Report format, either @:txt@ or @:xml@ |
 
 
+h3. Documentation
+
+Buildr offers support for using GroovyDoc to generate documentation from any Groovy sources in a project.  This is done using the @doc@ task:
+
+{% highlight sh %}
+$ buildr doc
+{% endhighlight %}
+
+This will use the same @.groovy@ sources used by the @compile@ task to produce GroovyDoc results in the @target/doc/@ directory.  By default, these sources are chosen only from the current project.  However, it is possible to override this and generate documentation from the sources in a sub-project (potentially more than one):
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc.from projects('foo:bar', 'foo')
+
+  define 'bar' do
+    # ...
+  end
+end
+{% endhighlight %}
+
+With this configuration, the @doc@ task will use sources from both @foo:bar@ and
+@foo@.
+
+The @doc@ task supports any option that the @groovydoc@ command does (e.g. @-windowtitle@).  To pass an option to the GroovyDoc generator, simply specify it using the @doc@ method:
+
+{% highlight ruby %}
+define 'foo' do
+  # ...
+
+  doc :windowtitle => 'Abandon All Hope, Ye Who Enter Here', :private => true
+end
+{% endhighlight %}
+
+The @doc@ task is *not* joint-compilation aware.  Thus, it will only generate GroovyDoc for mixed-source projects, it will not attempt to generate both JavaDoc and GroovyDoc.
+
+
 h2(#ruby).  Ruby
 
 h3.  Testing with Ruby
@@ -390,15 +530,15 @@ Because of the use of JRuby, you will notice that running ruby tests is faster w
 
 p(tip). When not running on JRuby, Buildr will use the @JRUBY_HOME@ environment variable to find the JRuby installation directory.  If no @JRUBY_HOME@ is set or it points to an empty directory, Buildr will prompt you to either install JRuby manually or let it  extract it for you.
 
-You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.1.4@).  For example:
+You can use the @build.yaml@ settings file to specify a particular version of JRuby (defaults to @1.4.0@ as of Buildr 1.3.5).  For example:
 
 {% highlight yaml %}
-jruby: 1.1.3
+jruby: 1.3.1
 {% endhighlight %}
 
 h4.  RSpec
 
-"RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself. 
+"RSpec":http://rspec.info/ is the de-facto BDD framework for ruby. It's the framework used to test Buildr itself.
 
 To use this framework in your project you can select it with @test.using :rspec@.