diff --git a/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties b/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties
index 82b74bdf1b2..26bee6df895 100644
--- a/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties
+++ b/dev-tools/src/main/resources/plugin-metadata/plugin-descriptor.properties
@@ -1,8 +1,26 @@
 # Elasticsearch plugin descriptor file
-# This file must be at the root of the plugin.
-# A plugin can be 'jvm', 'site', or both
+# This file must exist as 'plugin-descriptor.properties' at
+# the root directory of all plugins.
+#
+# A plugin can be 'site', 'jvm', or both.
+#
+### example site plugin for "foo":
+#
+# foo.zip <-- zip file for the plugin, with this structure:
+#   _site/ <-- the contents that will be served
+#   plugin-descriptor.properties <-- example contents below:
+#
+# site=true
+# description=My cool plugin
+# version=1.0
+#
+### example jvm plugin for "foo"
+#
+# foo.zip <-- zip file for the plugin, with this structure:
+#   <arbitrary name1>.jar <-- classes, resources, dependencies
+#   <arbitrary nameN>.jar <-- any number of jars
+#   plugin-descriptor.properties <-- example contents below:
 #
-# example jvm plugin:
 # jvm=true
 # classname=foo.bar.BazPlugin
 # description=My cool plugin
@@ -10,30 +28,43 @@
 # elasticsearch.version=2.0
 # java.version=1.7
 #
-# example site plugin:
-# site=true
-# description=My cool plugin
-# version=1.0
+### mandatory elements for all plugins:
 #
 # 'description': simple summary of the plugin
 description=${project.description}
+#
 # 'version': plugin's version
 version=${project.version}
 #
+### mandatory elements for site plugins:
+#
+# 'site': set to true to indicate contents of the _site/
+#  directory in the root of the plugin should be served.
+site=${elasticsearch.plugin.site}
+#
+### mandatory elements for jvm plugins :
+#
 # 'jvm': true if the 'classname' class should be loaded
-#  from jar files in the root directory of the plugin
+#  from jar files in the root directory of the plugin.
+#  Note that only jar files in the root directory are
+#  added to the classpath for the plugin! If you need
+#  other resources, package them into a resources jar.
 jvm=${elasticsearch.plugin.jvm}
-# 'classname': the name of the class to load. 
+#
+# 'classname': the name of the class to load, fully-qualified.
 classname=${elasticsearch.plugin.classname}
-# 'isolated': true if the plugin should have its own classloader.
-# passing false is deprecated, and only intended to support plugins 
-# that have hard dependencies against each other
-isolated=${elasticsearch.plugin.isolated}
+#
 # 'java.version' version of java the code is built against
 java.version=${maven.compiler.target}
+#
 # 'elasticsearch.version' version of elasticsearch compiled against
 elasticsearch.version=${elasticsearch.version}
 #
-# 'site': true if the contents of _site should be served
-site=${elasticsearch.plugin.site}
+### deprecated elements for jvm plugins :
+#
+# 'isolated': true if the plugin should have its own classloader.
+# passing false is deprecated, and only intended to support plugins 
+# that have hard dependencies against each other. If this is
+# not specified, then the plugin is isolated by default.
+isolated=${elasticsearch.plugin.isolated}
 #