Allow some projects with the javadoc-plugin applied to not be included in the aggregated javadoc

[wilkinsona]

In Spring Boot's build we publish two separate sets of javadoc:

• Gradle Plugin's javadoc
• Main javadoc aggregated from numerous projects

We want to apply the same conventions to both sets of javadoc, but don't want the Gradle Plugin's javadoc to be included in the main aggregated javadoc. I think this means that I'd like to be able to apply the javadoc-plugin across the board (to pick up any conventions for CSS etc) and then to be able to filter the projects that the aggregated javadoc plugin will use.

[rwinch]

Thanks for the report @wilkinsona

I'm thinking we might be able to do this by exposing an extension that allows configuring what projects should be used. It would default to work as is, but would allow configuring any projects you want. Is this something you think would work?

If so, any thoughts on the name of the extension? I believe it might be "bad form" to expose the extension and the task under the same name. Currently the task is named aggregateJavadoc. Thoughts?

[wilkinsona]

I don't think it needs to be an extension. Some customization on the aggregateJavadoc task would be sufficient.

An alternative approach would be to split things on the javadoc-plugin side into a piece (base plugin?) that configures the conventions and something on top that triggers consumption by the aggregating project.

[rwinch]

I don't think I understand the point on customization of aggregateJavadoc. It is just a Javadoc task and is fully customizable. It would mean you'd need to replicate all the logic which means you'd get no benefit. How do you imagine this would look from a consumption point of view?

The second suggestion does not make sense to me either. It seems to imply `javadoc-plugin' is configuring things now. However, it is inverted.

[wilkinsona]

It sounds like I've misunderstood the README. I was basing my understanding of the aggregateJavadoc task on this description:

This will create a task named aggregateJavadoc of type Javadoc. The task defaults the source and classpath to aggregate values based on all of the projects that contain the io.spring.javadoc plugin.

It's the "aggregate values based on all of the projects that contain the io.spring.javadoc plugin" that I'd like to be able to filter.

The second suggestion does not make sense to me either. It seems to imply `javadoc-plugin' is configuring things now. However, it is inverted.

My thinking there was that there could be something like io.spring.javadoc-base that applies the conventions for CSS and the like. Assuming that the aggregation side only consumes from projects that contain the io.spring.javadoc plugin, you could then benefit from the conventions without being part of the aggregated javadoc.

[rwinch]

Hmm..I think we are kind of on the same page but a little confused what you are confused about. Let try and put together a branch with what I had in mind and we can revise.

[rwinch]

@wilkinsona I think that this should be resolved via gh-1 See #1 (comment) Can you give the 0.0.2-SNAPSHOT a try? Note that you can resolve the SNAPSHOTs from the Spring plugins-snapshots repository now.

[wilkinsona]

Declaring implementation dependencies makes it possible to do what I want but it is more cumbersome than I would like. Rather than having to include every project that I want to be aggregated I'd prefer to be able to exclude those that I don't want to be aggregated. I prefer it this way around as the number of projects that we want to exclude is far smaller than the number of projects that we want to include.

[rwinch]

I don't want to add a filter mechanism to the plugin as it is already supported with a more powerful mechanism. I don't find this to be cumbersome:

def excluded = ['aggregator', 'module2', 'test-module']
dependencies {
    implementation rootProject.subprojects.findAll { p -> !excluded.contains(p.name) }
}

Perhaps I'm missing something?

[wilkinsona]

It'll work but it isn't declarative and it requires writing logic that deals with other projects. They're both things that we try to avoid in our build.gradle scripts and handle in a plugin instead.

[wilkinsona]

Another minor nit with using implementation dependencies isn't that it isn't very expressive. If you aren't familiar with how the javadoc aggregation works, it's not clear that dependencies in the implementation configuration are what will be aggregated. If a configuration-based approach is needed, using a custom configuration named aggregatedJavadoc or the like would make the intent clearer I think.

[rwinch]

Adding an exclude mechanism is not something I'd like to do. What happens if a user now wants to modify which projects are included as well?

It'll work but it isn't declarative and it requires writing logic that deals with other projects. They're both things that we try to avoid in our build.gradle scripts and handle in a plugin instead.

I don't understand this point. How would your proposal differ from this one?

Another minor nit with using implementation dependencies isn't that it isn't very expressive. If you aren't familiar with how the javadoc aggregation works, it's not clear that dependencies in the implementation configuration are what will be aggregated. If a configuration-based approach is needed, using a custom configuration named aggregatedJavadoc or the like would make the intent clearer I think.

I think this is a fair statement. We could change the configuration name to be something more expressive. Would you mind creating a separate ticket for this?

[wilkinsona]

I don't understand this point. How would your proposal differ from this one?

I'd like to be able to write something like this:

aggregateJavadoc {
    exclude 'aggregator', 'module2', 'test-module'
}

Perhaps exclude should be named excludeProject or similar, but the key thing is that it's entirely declarative and avoids writing logic in a script that iterates over all subproject or similar.

Would you mind creating a separate ticket for this?

Will do. Thanks.