compile.rb in buildr-0.20.0

- old
+ new

@@ -279,18 +279,159 @@
         super + filter.sources
       end
 
     end
 
+
+    # A convenient task for creating Javadocs from the project's compile task. Minimizes all
+    # the hard work to calling #from and #using.
+    #
+    # For example:
+    #   javadoc.from(projects("myapp:foo", "myapp:bar")).using(:windowtitle=>"My App")
+    # Or, short and sweet:
+    #   desc "My App"
+    #   define "myapp" do
+    #     . . .
+    #     javadoc projects("myapp:foo", "myapp:bar")
+    #   end
+    class JavadocTask < Rake::Task
+
+      def initialize(*args) #:nodoc:
+        super
+        @options = {}
+        @classpath = []
+        @sourcepath = []
+        @files = FileList[]
+        enhance do |task|
+          rm_rf target.to_s, :verbose=>false
+          Java.javadoc source_files, options.merge(:classpath=>classpath, :sourcepath=>sourcepath, :name=>name, :output=>target.to_s)
+          touch target.to_s, :verbose=>false
+        end
+      end
+
+      # The target directory for the generated Javadoc files.
+      attr_reader :target
+
+      # :call-seq:
+      #   into(path) => self
+      #
+      # Sets the target directory and returns self. This will also set the Javadoc task
+      # as a prerequisite to a file task on the target directory.
+      #
+      # For example:
+      #   package :zip, :classifier=>"docs", :include=>javadoc.target
+      def into(path)
+        path = File.expand_path(path.to_s)
+        @target = file(path).enhance([self]) unless @target && @target.to_s == path
+        self
+      end
+
+      # :call-seq:
+      #   include(*files) => self
+      #
+      # Includes additional source files and directories when generating the documentation
+      # and returns self. When specifying a directory, includes all .java files in that directory.
+      def include(*files)
+        @files.include *files
+        self
+      end
+
+      # :call-seq:
+      #   exclude(*files) => self
+      #
+      # Excludes source files and directories from generating the documentation.
+      def exclude(*files)
+        @files.exclude *files
+        self
+      end
+
+      # Classpath dependencies.
+      attr_accessor :classpath
+
+      # :call-seq:
+      #   with(*artifacts) => self
+      #
+      # Adds files and artifacts as classpath dependencies, and returns self.
+      def with(*specs)
+        @classpath |= artifacts(specs.flatten).uniq
+        self
+      end
+
+      # Additional sourcepaths that are not part of the documented files.
+      attr_accessor :sourcepath
+        
+      # Returns the Javadoc options.
+      attr_reader :options
+
+      # :call-seq:
+      #   using(options) => self
+      #
+      # Sets the Javadoc options from a hash and returns self.
+      #
+      # For example:
+      #   javadoc.using :windowtitle=>"My application"
+      def using(options)
+        options.each { |key, value| @options[key] = value }
+        self
+      end
+
+      # :call-seq:
+      #   from(*sources) => self
+      #
+      # Includes files, directories and projects in the Javadoc documentation and returns self.
+      #
+      # You can call this method with Java source files and directories containing Java source files
+      # to include these files in the Javadoc documentation, similar to #include. You can also call
+      # this method with projects. When called with a project, it includes all the source files compiled
+      # by that project and classpath dependencies used when compiling.
+      #
+      # For example:
+      #   javadoc.from projects("myapp:foo", "myapp:bar")
+      def from(*sources)
+        sources.flatten.each do |source|
+          case source
+          when Project
+            self.include source.compile.sources
+            self.with source.compile.classpath 
+          when Rake::Task, String
+            self.include source
+          else
+            fail "Don't know how to generate Javadocs from #{source || 'nil'}"
+          end
+        end
+        self
+      end
+
+      def prerequisites() #:nodoc:
+        super + @files + classpath + sourcepath
+      end
+
+      def source_files() #:nodoc:
+        @source_files ||= @files.map(&:to_s).
+          map { |file| File.directory?(file) ? FileList[File.join(file, "**/*.java")] : file }.
+          flatten.reject { |file| @files.exclude?(file) }
+      end
+
+      def needed?() #:nodoc:
+        return false if source_files.empty?
+        return true unless File.exist?(target.to_s)
+        source_files.map { |src| File.stat(src.to_s).mtime }.max > File.stat(target.to_s).mtime
+      end
+
+    end
+
   end
 
 
   # Local task to execute the compile task of the current project.
   # This task is not itself a compile task.
   desc "Compile all projects"
   Project.local_task("compile") { |name| "Compiling #{name}" }
 
+  desc "Create the Javadocs for this project"
+  Project.local_task("javadoc")
+
   class Project
 
     # :call-seq:
     #   prepare(*prereqs) => task
     #   prepare(*prereqs) { |task| .. } => task
@@ -354,10 +495,27 @@
     #   resources.filter.using "Copyright"=>"Acme Inc, 2007"
     def resources(*prereqs, &block)
       task("resources").enhance prereqs, &block
     end
 
+    # :call-seq:
+    #   javadoc(*sources) => JavadocTask
+    #
+    # This method returns the project's Javadoc task. It also accepts a list of source files,
+    # directories and projects to include when generating the Javadocs.
+    #
+    # By default the Javadoc task uses all the source directories from compile.sources and generates
+    # Javadocs in the target/javadoc directory. This method accepts sources and adds them by calling
+    # JavadocsTask#from.
+    #
+    # For example, if you want to generate Javadocs for a given project that includes all source files
+    # in two of its sub-projects:
+    #   javadoc projects("myapp:foo", "myapp:bar").using(:windowtitle=>"Docs for foo and bar")
+    def javadoc(*sources, &block)
+      task("javadoc").from(*sources).enhance &block
+    end
+
   end
 
   Project.on_define do |project|
     prepare = task("prepare")
     # Resources task is a filter.
@@ -366,14 +524,21 @@
     # Compile task requires prepare and performs resources, if anything compiled.
     compile = Java::CompileTask.define_task("compile"=>[prepare, resources]) { |task| project.resources.invoke }
     project.path_to("src/main/java").tap { |dir| compile.from dir if File.exist?(dir) }
     compile.into project.path_to("target/classes")
     resources.filter.into project.compile.target
+    Java::JavadocTask.define_task("javadoc"=>prepare).tap do |javadoc|
+      javadoc.into project.path_to("target/javadoc")
+      javadoc.using :windowtitle=>project.comment || project.name
+    end
     project.recursive_task("compile")
     project.clean { verbose(false) { rm_rf project.path_to("target") } }
 
     project.enhance do |project|
+      # This comes last because the target path may change.
       project.build project.compile.target
+      # This comes last so we can determine all the source paths and classpath dependencies.
+      project.javadoc.from project
     end
   end
 
 end