[GRADLE-1876] Aggregation of javadocs in muli-project build is cumbersome Created: 29/Oct/11  Updated: 10/Feb/17  Resolved: 10/Feb/17

Status: Resolved
Project: Gradle
Affects Version/s: 1.0-milestone-3
Fix Version/s: None

Type: New Feature
Reporter: Jordan Zimmerman Assignee: Unassigned
Resolution: Won't Fix Votes: 5


 Description   

As best I can tell, the only way to aggregate Javadoc for a multi-project build is:

task docs(type: Javadoc) {
    source subprojects.collect {project -> project.sourceSets.main.allJava } 
    classpath = files(subprojects.collect {project -> project.sourceSets.main.compileClasspath}) 
    destinationDir = new File(projectDir, 'docs')
}

That bit makes Maven look easy I suggest some kind of method or propety in the subproject tag. e.g.

subprojects  {
    aggregateJavaDoc(directory)
    ...
}


 Comments   
Comment by Andrew Oberstar [ 29/Oct/11 ]

Or maybe a switch on the javadoc task, that has it pull information from the Javadoc tasks of its subprojects.

task docs(type: Javadoc) {
  aggregateSubprojects = true
}
Comment by Luke Daley [ 01/Nov/11 ]

Hi Andrew,

The problem with adding a kind of shortcut syntax is that it's not quite flexible enough. Someone may want all subprojects but one for example.

You can shorten the aggregate task to:

task docs(type: Javadoc) {
    source subprojects*.javaDoc*.source
    classpath files(subprojects.classpath) 
}

(BTW, the fact that you have to use files() for classpath is a bug that will be fixed)

What might be good enough is a projects() method on the Javadoc task that shortcuts this…

task docs(type: Javadoc) {
    projects subprojects
}

That way it's concise, yet still powerful. How does that strike you?

Comment by Philip Crotwell [ 01/Nov/11 ]


A slightly different take would be to follow "project" dependencies. If I have appA, libB and libC all as part of a multiproject, with libB a dependency of appA, it would be nice if there was an easy way to have the generated javadocs for appA automatically include the javadocs for libB but not for libC.

Comment by Andrew Oberstar [ 01/Nov/11 ]

Luke, that option is definitely better than my suggestion.

Philip, how would you configure that on the task?

The flexibility will still be dependent on how the Javadoc task pulls information from those projects. Would it just look for a Javadoc task named "javadoc", or is there something more generic it could do? Maybe rather than adding projects, you add other Javadoc tasks that it should aggregate.

task docs(type: Javadoc) {
  tasks subprojects*.javadoc
}
Comment by Leland Starr [ 20/Jul/12 ]

even with work around approach:
task docs(type: Javadoc) {
source subprojects.collect

{project -> project.sourceSets.main.allJava }


classpath = files(subprojects.collect

{project -> project.sourceSets.main.compileClasspath}

)
destinationDir = new File(projectDir, 'docs')
}
I run into OutOfMemoryError issues running with GRADLE_OPTS -Xmx3000m, the solution that would be nice is for the javadoc task to run on individual projects the way it does, and then a final task that creates a master index file, maybe as part of a deploy style task.

Comment by Benjamin Muschko [ 15/Nov/16 ]

As announced on the Gradle blog we are planning to completely migrate issues from JIRA to GitHub.

We intend to prioritize issues that are actionable and impactful while working more closely with the community. Many of our JIRA issues are inactionable or irrelevant. We would like to request your help to ensure we can appropriately prioritize JIRA issues you’ve contributed to.

Please confirm that you still advocate for your JIRA issue before December 10th, 2016 by:

  • Checking that your issues contain requisite context, impact, behaviors, and examples as described in our published guidelines.
  • Leave a comment on the JIRA issue or open a new GitHub issue confirming that the above is complete.

We look forward to collaborating with you more closely on GitHub. Thank you for your contribution to Gradle!

Comment by Benjamin Muschko [ 10/Feb/17 ]

Thanks again for reporting this issue. We haven't heard back from you after our inquiry from November 15th. We are closing this issue now. Please create an issue on GitHub if you still feel passionate about getting it resolved.

Generated at Wed Jun 30 12:06:44 CDT 2021 using Jira 8.4.2#804003-sha1:d21414fc212e3af190e92c2d2ac41299b89402cf.