Further document the pom hack

We have a "HUGE HACK" that allows us to publish zip artifacts to
Sonatype's OSS repository without javadoc and source jars. We don't
include those jars because the zip is just a repackaging of the
core and module jars for which we already publish the javadoc and
source jars. So we have a hack to publish the zip artifact when the
pom says the project is of type 'pom'.

buildSrc/src/main/groovy/org/elasticsearch/gradle/plugin/PluginBuildPlugin.groovy

@@ -221,13 +221,16 @@ public class PluginBuildPlugin extends BuildPlugin {
                 zip(MavenPublication) {
                     artifact project.bundlePlugin
                 }
-                // HUGE HACK: the underlying maven publication library refuses to deploy any attached artifacts
-                // when the packaging type is set to 'pom'. So here we create another publication using the same
-                // name that has the "real" pom, and rely on the fact that gradle will execute the publish tasks
-                // in alphabetical order. We cannot setup a dependency between the tasks because the publishing
-                // tasks are created *extremely* late in the configuration phase, so that we cannot get ahold
-                // of the actual task. Furthermore, this entire hack only exists so we can make publishing to
-                // maven local work, since we publish to maven central externally.
+                /* HUGE HACK: the underlying maven publication library refuses to deploy any attached artifacts
+                 * when the packaging type is set to 'pom'. But Sonatype's OSS repositories require source files
+                 * for artifacts that are of type 'zip'. We already publish the source and javadoc for Elasticsearch
+                 * under the various other subprojects. So here we create another publication using the same
+                 * name that has the "real" pom, and rely on the fact that gradle will execute the publish tasks
+                 * in alphabetical order. This lets us publish the zip file and even though the pom says the
+                 * type is 'pom' instead of 'zip'. We cannot setup a dependency between the tasks because the
+                 * publishing tasks are created *extremely* late in the configuration phase, so that we cannot get
+                 * ahold of the actual task. Furthermore, this entire hack only exists so we can make publishing to
+                 * maven local work, since we publish to maven central externally. */
                 zipReal(MavenPublication) {
                     pom.withXml { XmlProvider xml ->
                         Node root = xml.asNode()

distribution/integ-test-zip/build.gradle

@@ -35,7 +35,16 @@ publishing {
       artifactId 'elasticsearch'
       artifact buildZip
     }
-    // TODO explain why we can't use the pom build by nebula
+    /* HUGE HACK: the underlying maven publication library refuses to deploy any attached artifacts
+     * when the packaging type is set to 'pom'. But Sonatype's OSS repositories require source files
+     * for artifacts that are of type 'zip'. We already publish the source and javadoc for Elasticsearch
+     * under the various other subprojects. So here we create another publication using the same
+     * name that has the "real" pom, and rely on the fact that gradle will execute the publish tasks
+     * in alphabetical order. This lets us publish the zip file and even though the pom says the
+     * type is 'pom' instead of 'zip'. We cannot setup a dependency between the tasks because the
+     * publishing tasks are created *extremely* late in the configuration phase, so that we cannot get
+     * ahold of the actual task. Furthermore, this entire hack only exists so we can make publishing to
+     * maven local work, since we publish to maven central externally. */
     nebulaRealPom(MavenPublication) {
       artifactId 'elasticsearch'
       pom.packaging = 'pom'

distribution/zip/build.gradle

@@ -35,7 +35,16 @@ publishing {
       artifactId 'elasticsearch'
       artifact buildZip
     }
-    // TODO explain why we can't use the pom build by nebula
+    /* HUGE HACK: the underlying maven publication library refuses to deploy any attached artifacts
+     * when the packaging type is set to 'pom'. But Sonatype's OSS repositories require source files
+     * for artifacts that are of type 'zip'. We already publish the source and javadoc for Elasticsearch
+     * under the various other subprojects. So here we create another publication using the same
+     * name that has the "real" pom, and rely on the fact that gradle will execute the publish tasks
+     * in alphabetical order. This lets us publish the zip file and even though the pom says the
+     * type is 'pom' instead of 'zip'. We cannot setup a dependency between the tasks because the
+     * publishing tasks are created *extremely* late in the configuration phase, so that we cannot get
+     * ahold of the actual task. Furthermore, this entire hack only exists so we can make publishing to
+     * maven local work, since we publish to maven central externally. */
     nebulaRealPom(MavenPublication) {
       artifactId 'elasticsearch'
       pom.packaging = 'pom'