Possible error in maven-publish documentation

I think Example 2 in this documentation has an error Maven Publish Plugin

It is using maven(MavenPublication) instead of mavenJava(MavenPublication).

publishing {
    publications {
        maven(MavenPublication) {
            groupId = 'org.gradle.sample'
            artifactId = 'library'
            version = '1.1'

            from components.java

That example is the only example I can find that shows it using maven(MavenPublication) instead of mavenJava(MavenPublication(). I have even looked through my own builds and I have never used maven(MavenPublication).

If that isn’t an error what is the difference between maven(MavenPublication) and mavenJava(MavenPublication()?

Actually it is just an arbitrary name you choose to differentiate multiple publications you configure.
You can name it “fritz” if you like.

That little tidbit of information should probably be mentioned in the documentation. I can see how that would be confusing to someone. All other examples show the name as mavenJava so it kind of looks like you are calling a mavenJava method. How would someone know that is a free-form name?

Well, that’s Groovy magic. :slight_smile:
If you look at the Kotlin variant of the snippet it is more clear that this is just a string.
Feel free to open an improvement request as GitHub issue if you think it is not clear enough.
But the documentation uses a lot of different names here, maven, mavenJava, main, myLibrary , binary, binaryAndSources, myDistribution, …
It is also the same for all named domain object collections like for example source sets or configurations.

Also the documentation says

This extension provides a container of named publications and a container of named repositories.

And shows that the task names depend on the publication name.

It also says

To learn how to define and use publications, see the section on basic publishing.

where on the linked page it shows how to define a publication named myLibrary and also explains

This defines a publication called “myLibrary” that can be published to a Maven repository by virtue of its type: MavenPublication.

Tbh. I personally don’t see much improvement potential in that regard. :slight_smile:

How about this under Example 2:

NOTE: In this example the name “maven” is a free-form name and can be anything that makes sense for your build. Learn more about this in the section on basic publishing.


And what is the reasoning to not include that note under each and every such example and the same for source sets, configurations and any other named domain object container?

In my opinion this brings absolutely no benefit and just adds unnecessary clutter to the docs.

But hey, as I said, you are free to open an improvement request on GitHub.
I’m just a Gradle user like you.

To be honest this was also one of my biggest problem with the Groovy DSL.
After switching to Kotlin, everything becomes more readable.

The methodMissing feature of Groovy is quite surprising for Groovy-noobs like me. And I would argue it is still confusing even when you’re aware of its existence, because it’s really hard to distinguish this from other well-defined methods (neither in the IDE nor in snippets in the doc or on the web).

I believe it would be better if Gradle didn’t use this feature that much, and used something that looked like an actual string, just like in the Kotlin DSL. That being said, while Kotlin can add an invoke operator on String as a member extension, I’m not sure if this is possible in Groovy to add a Call operator on the String metaclass but only in the context of a particular container.

IMO it may not be necessary to add this kind of note for every NamedDomainObjectContainer. Writing good documentation is hard, and finding the right balance on where exactly to put this note is one of these hard things. It doesn’t mean it shouldn’t be done anywhere.
I think it should be done in places where people are more likely to see this for the first time. Maven publication is one of these places IMO (you might not have read any other thing in the doc, but you want to publish something now).

That’s why there is in this exact place a link in this sentence:

To learn how to define and use publications, see the section on basic publishing .

So imho it is pretty well covered.

But as I said, this is just my opinion and you are free to request a docu change from Gradle guys, I’m just a community member like you. :slight_smile:

Regarding the methodMissing, the point is, that Gradle build scripts are a DSL, so thinking in methods is the wrong way actually.
For me it helped greatly that I first read a book about Groovy before I wrote my first bigger Gradle build to better understand how things work and why the work as they do.

But as an average user of the Groovy DSL, it is better to not see those as method calls, but as what it is.
A DSL that allows you to declaratively describe your project / build.