Merge pull request #1392 from dominiquebrice/javadoc_update

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

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

@@ -48,7 +48,10 @@ 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, or it may directly define extension
+ * points annotated with {@link hudson.Extension}. For a list of extension
+ * points, see <a href="https://wiki.jenkins-ci.org/display/JENKINS/Extension+points">
+ * https://wiki.jenkins-ci.org/display/JENKINS/Extension+points</a>.
  *
  * <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

@@ -42,6 +42,7 @@ import java.util.Collections;
  * with the {@link LabelAtom} object.
  *
  * @author Kohsuke Kawaguchi
+ * @see hudson.model.labels.LabelAtomPropertyDescriptor
  * @since 1.373
  */
 @ExportedBean

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

@@ -31,6 +31,11 @@ import hudson.model.Descriptor;
  *
  * <p>
  * Put {@link Extension} on your descriptor implementation to have it auto-registered.
+ * 
+ * <p>
+ * When extending this class, override <code>Descriptor.getDisplayName()</code>. In the
+ * context of LabelAtomPropertyDescriptor, this function is used to determine the label of
+ * the checkbox shown in the label's configuration page to activate the extension.
  *
  * @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