Uploaded image for project: 'Gradle'
  1. Gradle
  2. GRADLE-1876

Aggregation of javadocs in muli-project build is cumbersome

    Details

    • Type: New Feature
    • Status: Resolved
    • Resolution: Won't Fix
    • Affects Version/s: 1.0-milestone-3
    • Fix Version/s: None

      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)
          ...
      }
      

        Activity

        Hide
        ajoberstar Andrew Oberstar added a comment -

        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
        }
        
        Show
        ajoberstar Andrew Oberstar added a comment - 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 }
        Hide
        ldaley Luke Daley added a comment -

        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?

        Show
        ldaley Luke Daley added a comment - 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?
        Hide
        crotwell Philip Crotwell added a comment -


        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.

        Show
        crotwell Philip Crotwell added a comment - 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.
        Hide
        ajoberstar Andrew Oberstar added a comment -

        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
        }
        
        Show
        ajoberstar Andrew Oberstar added a comment - 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 }
        Hide
        base32 Leland Starr added a comment -

        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.

        Show
        base32 Leland Starr added a comment - 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.
        Hide
        bmuschko Benjamin Muschko added a comment -

        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!

        Show
        bmuschko Benjamin Muschko added a comment - 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!
        Hide
        bmuschko Benjamin Muschko added a comment -

        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.

        Show
        bmuschko Benjamin Muschko added a comment - 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.

          People

          • Assignee:
            Unassigned
            Reporter:
            randgalt Jordan Zimmerman
          • Votes:
            5 Vote for this issue
            Watchers:
            8 Start watching this issue

            Dates

            • Created:
              Updated:
              Resolved:

              Development