Typically conventions are used to pass values down to real implementations, i.e. defaults. The Maven plugin adds a maven convention with two pom methods on it:
http://gradle.org/docs/current/dsl/org.gradle.api.Project.html#org.gradle.api.Project:pom()
Given how all other conventions work, I would have assumed this would be used by MavenDeployer, to centrally apply some defaults. This is definitely not the case. It’s actually only usable to create a pom object. I don’t think there are many example of such a high level convention which is used as a factory for creating an object. I’m not sure if the bug is to remove the pom methods, or to enhance MavenPomMetaInfoProvider to use this convention for more than just pomDir.
The documentation is technically accurate in that it’s used to create a MavenPom object. Given it’s location on Project, it’s confusing. I don’t think a documentation change will alleviate it’s awkwardness.