Updating javadoc of Plugin, LabelAtomProperty, GlobalConfiguration with my...

Updating javadoc of Plugin, LabelAtomProperty, GlobalConfiguration with my observations from working on my plugin

core/src/main/java/hudson/Plugin.java

@@ -48,7 +48,7 @@ import com.thoughtworks.xstream.XStream;
  * Base class of Hudson plugin.
  *
  * <p>
- * A plugin needs to derive from this class.
+ * A plugin may derive from this class.
  *
  * <p>
  * One instance of a plugin is created by Hudson, and used as the entry point

core/src/main/java/hudson/model/labels/LabelAtomProperty.java

@@ -40,6 +40,17 @@ import java.util.Collections;
  * Plugins can contribute this extension point to add additional data or UI actions to {@link LabelAtom}.
  * {@link LabelAtomProperty}s show up in the configuration screen of a label, and they are persisted
  * with the {@link LabelAtom} object.
+ * 
+ * <h2>Implementation hints</h2>
+ * <ul>
+ * <li>extend this class and define a static inner class extending {@link hudson.model.labels.LabelAtomPropertyDescriptor}</li>
+ * <li>in the inner class override <code>getDisplayName()</code>. This function returns the name of the option shown in the label
+ * configuration page to activate your extension</li>
+ * <li>if you need additional parameters in this page when activating your extension, provide a <tt>config.jelly</tt> file</li>
+ * <li>when the user saves the label configuration page with your extension activated, Jenkins calls the corresponding
+ * {@link org.kohsuke.stapler.DataBoundConstructor}-annotated constructor in your LabelAtomProperty subclass</li>
+ * <li>override the <code>getActions()</code> function to return your additional {@link hudson.model.Action}(s)</li>
+ * </ul>
  *
  * @author Kohsuke Kawaguchi
  * @since 1.373

core/src/main/java/jenkins/model/GlobalConfiguration.java

@@ -6,17 +6,28 @@ import hudson.model.Describable;
 import hudson.model.Descriptor;
 
 /**
- * Convenient base class for extensions that contributes to the system configuration page but nothing else.
+ * Convenient base class for extensions that contributes to the system configuration page but nothing
+ * else, or to manage the global configuration of a plugin implementing several extension points.
  *
  * <p>
- * All {@link Descriptor}s are capable of contributing fragment to the system config page, so
- * this extension point is is really only for those who don't want to contribute anything else.
- * If you are implementing other extension points and that would like to expose some global configuration,
- * you can do so with <tt>global.groovy</tt> from your {@link Descriptor} instance.
+ * All {@link Descriptor}s are capable of contributing fragment to the system config page. If you are
+ * implementing other extension points that need to expose some global configuration, you can do so
+ * with <tt>global.groovy</tt> or <tt>global.jelly</tt> from your {@link Descriptor} instance. However
+ * each <tt>global.*</tt> file will appear as its own section in the global configuration page.
+ * 
+ * <p>
+ * An option to present a single section for your plugin in the Jenkins global configuration page is
+ * to use this class to manage the configuration for your plugin and its extension points. To access
+ * properties defined in your GlobalConfiguration subclass, here are two possibilities:
+ * <ul><li>@{@link javax.inject.Inject} into your other {@link hudson.Extension}s (so this does <i>not</i> work
+ * for classes not annotated with {@link hudson.Extension})</li>
+ * <li>access it via a call to <code>GlobalConfiguration.all().get(&lt;your GlobalConfiguration subclass&gt;.class)
+ * </code></li></ul>
  *
  * <h2>Views</h2>
  * <p>
- * Subtypes of this class should define <tt>config.groovy</tt> that gets pulled into the system configuration page.
+ * Subtypes of this class should define a <tt>config.groovy</tt> file or <tt>config.jelly</tt> file
+ * that gets pulled into the system configuration page.
  * 
  *
  * @author Kohsuke Kawaguchi