Merge changes Ie3606db7,Ifa6a8eb4

* changes:
  Fix warnings when generating JavaDoc
  Buck: generate javadocs for plugin and extension API

BUCK

@@ -7,12 +7,15 @@ gerrit_war(name = 'withdocs', docs = True)
 gerrit_war(name = 'release',  docs = True, context = ['//plugins:core.zip'])
 
 API_DEPS = [
-  ':extension-api',
-  ':extension-api-src',
-  ':plugin-api',
-  ':plugin-api-src',
-  ':plugin-gwtui',
-  ':plugin-gwtui-src',
+  '//gerrit-extension-api:extension-api',
+  '//gerrit-extension-api:extension-api-src',
+  '//gerrit-extension-api:extension-api-javadoc',
+  '//gerrit-plugin-api:plugin-api',
+  '//gerrit-plugin-api:plugin-api-src',
+  '//gerrit-plugin-api:plugin-api-javadoc',
+  '//gerrit-plugin-gwtui:gwtui-api',
+  '//gerrit-plugin-gwtui:gwtui-api-src',
+  '//gerrit-plugin-gwtui:gwtui-api-javadoc',
 ]
 
 genrule(
@@ -24,73 +27,3 @@ genrule(
   deps = API_DEPS,
   out = 'api.zip',
 )
-
-java_binary(
-  name = 'extension-api',
-  deps = [':extension-lib'],
-  visibility = ['//tools/maven:'],
-)
-
-java_library(
-  name = 'extension-lib',
-  deps = [
-    '//gerrit-extension-api:api',
-    '//lib/guice:guice',
-    '//lib/guice:guice-servlet',
-    '//lib:servlet-api-3_0',
-  ],
-  export_deps = True,
-  visibility = ['PUBLIC'],
-)
-
-genrule(
-  name = 'extension-api-src',
-  cmd = 'ln -s $(location //gerrit-extension-api:api-src) $OUT',
-  deps = ['//gerrit-extension-api:api-src'],
-  out = 'extension-api-src.jar',
-  visibility = ['//tools/maven:'],
-)
-
-PLUGIN_API = [
-  '//gerrit-server:server',
-  '//gerrit-pgm:init-api',
-  '//gerrit-sshd:sshd',
-  '//gerrit-httpd:httpd',
-]
-
-java_binary(
-  name = 'plugin-api',
-  deps = [':plugin-lib'],
-  visibility = ['//tools/maven:'],
-)
-
-java_library(
-  name = 'plugin-lib',
-  deps = PLUGIN_API + ['//lib:servlet-api-3_0'],
-  export_deps = True,
-  visibility = ['PUBLIC'],
-)
-
-java_binary(
-  name = 'plugin-api-src',
-  deps = [
-    '//gerrit-extension-api:api-src',
-  ] + [d + '-src' for d in PLUGIN_API],
-  visibility = ['//tools/maven:'],
-)
-
-genrule(
-  name = 'plugin-gwtui',
-  cmd = 'ln -s $(location //gerrit-plugin-gwtui:client) $OUT',
-  deps = ['//gerrit-plugin-gwtui:client'],
-  out = 'plugin-gwtui.jar',
-  visibility = ['//tools/maven:'],
-)
-
-genrule(
-  name = 'plugin-gwtui-src',
-  cmd = 'ln -s $(location //gerrit-plugin-gwtui:src) $OUT',
-  deps = ['//gerrit-plugin-gwtui:src'],
-  out = 'plugin-gwtui-src.jar',
-  visibility = ['//tools/maven:'],
-)

gerrit-extension-api/BUCK

@@ -1,4 +1,5 @@
 SRC = 'src/main/java/com/google/gerrit/extensions/'
+SRCS = glob([SRC + '**/*.java'])
 
 gwt_module(
   name = 'client',
@@ -7,6 +8,24 @@ gwt_module(
   visibility = ['PUBLIC'],
 )
 
+java_binary(
+  name = 'extension-api',
+  deps = [':extension-lib'],
+  visibility = ['PUBLIC'],
+)
+
+java_library(
+  name = 'extension-lib',
+  deps = [
+    ':api',
+    '//lib/guice:guice',
+    '//lib/guice:guice-servlet',
+    '//lib:servlet-api-3_0',
+  ],
+  export_deps = True,
+  visibility = [],
+)
+
 java_library2(
   name = 'api',
   srcs = glob([SRC + '**/*.java']),
@@ -15,7 +34,20 @@ java_library2(
 )
 
 java_sources(
-  name = 'api-src',
-  srcs = glob([SRC + '**/*.java']),
+  name = 'extension-api-src',
+  srcs = SRCS,
+  visibility = ['PUBLIC'],
+)
+
+java_doc(
+  name = 'extension-api-javadoc',
+  title = 'Gerrit Review Extension API Documentation',
+  pkg = 'com.google.gerrit.extensions',
+  paths = ['$SRCDIR/src/main/java'],
+  srcs = SRCS,
+  deps = [
+    '//lib/guice:javax-inject',
+    '//lib/guice:guice_library'
+  ],
   visibility = ['PUBLIC'],
 )

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/CapabilityScope.java

@@ -24,7 +24,7 @@ public enum CapabilityScope {
    *
    * If {@code @RequiresCapability} is used within the core Gerrit Code Review
    * server (and thus is outside of a plugin) the scope is the core server and
-   * will use {@link com.google.gerrit.common.data.GlobalCapability}.
+   * will use {@code com.google.gerrit.common.data.GlobalCapability}.
    */
   CONTEXT,
 

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/Export.java

@@ -28,19 +28,19 @@ import java.lang.annotation.Target;
  * Plugins or extensions using auto-registration should apply this annotation to
  * any non-abstract class they want exported for access.
  * <p>
- * For SSH commands the @Export annotation names the subcommand:
+ * For SSH commands the {@literal @Export} annotation names the subcommand:
  *
  * <pre>
- *   @Export("print")
+ *   {@literal @Export("print")}
  *   class MyCommand extends SshCommand {
  * </pre>
  *
- * For HTTP servlets, the @Export annotation names the URL the servlet is bound
- * to, relative to the plugin or extension's namespace within the Gerrit
- * container.
+ * For HTTP servlets, the {@literal @Export} annotation names the URL the
+ * servlet is bound to, relative to the plugin or extension's namespace within
+ * the Gerrit container.
  *
  * <pre>
- *  @Export("/index.html")
+ *  {@literal @Export("/index.html")}
  *  class ShowIndexHtml extends HttpServlet {
  * </pre>
  */

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/PluginCanonicalWebUrl.java

@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
  * the canonical web URL under which the plugin is available:
  *
  * <pre>
- *  @Inject
+ *  {@literal @Inject}
  *  MyType(@PluginCanonicalWebUrl String myUrl) {
  *  ...
  *  }

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/PluginData.java

@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
  * a directory where it can store configuration or other data that is private:
  *
  * <pre>
- * @Inject
+ * {@literal @Inject}
  * MyType(@PluginData java.io.File myDir) {
  *   new FileInputStream(new File(myDir, &quot;my.config&quot;));
  * }

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/PluginName.java

@@ -29,7 +29,7 @@ import java.lang.annotation.Target;
  * the name that an administrator has installed the plugin or extension under:
  *
  * <pre>
- *  @Inject
+ *  {@literal @Inject}
  *  MyType(@PluginName String myName) {
  *  ...
  *  }

gerrit-extension-api/src/main/java/com/google/gerrit/extensions/annotations/RequiresCapability.java

@@ -21,8 +21,8 @@ import java.lang.annotation.Retention;
 import java.lang.annotation.Target;
 
 /**
- * Annotation on {@link com.google.gerrit.sshd.SshCommand} or
- * {@link com.google.gerrit.httpd.restapi.RestApiServlet} declaring a
+ * Annotation on {@code com.google.gerrit.sshd.SshCommand} or
+ * {@code com.google.gerrit.httpd.restapi.RestApiServlet} declaring a
  * capability must be granted.
  */
 @Target({ElementType.TYPE})

gerrit-plugin-api/BUCK

@@ -0,0 +1,47 @@
+SRCS = [
+  'gerrit-server/src/main/java/',
+  'gerrit-httpd/src/main/java/',
+  'gerrit-sshd/src/main/java/'
+]
+
+PLUGIN_API = [
+  '//gerrit-server:server',
+  '//gerrit-pgm:init-api',
+  '//gerrit-sshd:sshd',
+  '//gerrit-httpd:httpd',
+]
+
+java_binary(
+  name = 'plugin-api',
+  deps = [':lib'],
+  visibility = ['PUBLIC'],
+)
+
+java_library(
+  name = 'lib',
+  deps = PLUGIN_API + ['//lib:servlet-api-3_0'],
+  export_deps = True,
+  visibility = [],
+)
+
+java_binary(
+  name = 'plugin-api-src',
+  deps = [
+    '//gerrit-extension-api:extension-api-src',
+  ] + [d + '-src' for d in PLUGIN_API],
+  visibility = ['PUBLIC'],
+)
+
+java_doc(
+  name = 'plugin-api-javadoc',
+  title = 'Gerrit Review Plugin API Documentation',
+  pkg = 'com.google.gerrit',
+  paths = [n for n in SRCS],
+  srcs = glob([n + '**/*.java' for n in SRCS]),
+  deps = [
+    ':plugin-api',
+    '//lib/bouncycastle:bcprov',
+    '//lib/bouncycastle:bcpg',
+  ],
+  visibility = ['PUBLIC'],
+)

gerrit-plugin-gwtui/BUCK

@@ -1,20 +1,33 @@
 SRC = 'src/main/java/com/google/gerrit/'
+SRCS = glob([SRC + '**/*.java'])
+
+DEPS = [
+  '//lib/gwt:user',
+  '//lib/gwt:dev',
+]
 
 gwt_module(
-  name = 'client',
-  srcs = glob([SRC + '**/*.java']),
+  name = 'gwtui-api',
+  srcs = SRCS,
   gwtxml = SRC + 'Plugin.gwt.xml',
   resources = glob(['src/main/resources/**/*']),
-  deps = [
-    '//lib/gwt:user',
-    '//lib/gwt:dev',
-  ],
+  deps = DEPS,
   visibility = ['PUBLIC'],
 )
 
 java_library(
-  name = 'src',
+  name = 'gwtui-api-src',
   srcs = [],
   resources = glob(['src/main/**/*']),
   visibility = ['PUBLIC'],
 )
+
+java_doc(
+  name = 'gwtui-api-javadoc',
+  title = 'Gerrit Review GWT Extension API Documentation',
+  pkg = 'com.google.gerrit.plugin',
+  paths = ['$SRCDIR/src/main/java'],
+  srcs = SRCS,
+  deps = DEPS,
+  visibility = ['PUBLIC'],
+)

gerrit-server/src/main/java/com/google/gerrit/server/contact/HttpContactStoreConnection.java

@@ -17,7 +17,7 @@ import java.net.HttpURLConnection;
 import java.net.URL;
 import java.net.URLConnection;
 
-/** {@link ContactStoreConnection} with an underlying {@HttpURLConnection}. */
+/** {@link ContactStoreConnection} with an underlying {@literal @HttpURLConnection}. */
 public class HttpContactStoreConnection implements ContactStoreConnection {
   public static Module module() {
     return new AbstractModule() {

gerrit-server/src/main/java/com/google/gerrit/server/git/SubmitStrategy.java

@@ -24,7 +24,7 @@ import com.google.gerrit.server.index.ChangeIndexer;
 
 import org.eclipse.jgit.lib.ObjectInserter;
 import org.eclipse.jgit.lib.PersonIdent;
-import org.eclipse.jgit.lib.RefUpdate;
+import org.eclipse.jgit.lib.RefUpdate.Result;
 import org.eclipse.jgit.lib.Repository;
 import org.eclipse.jgit.revwalk.RevCommit;
 import org.eclipse.jgit.revwalk.RevFlag;
@@ -164,12 +164,12 @@ public abstract class SubmitStrategy {
 
   /**
    * Returns whether a merge that failed with
-   * {@link RefUpdate.Result#LOCK_FAILURE} should be retried.
+   * {@link Result#LOCK_FAILURE} should be retried.
    *
    * May be overwritten by subclasses.
    *
    * @return <code>true</code> if a merge that failed with
-   *         {@link RefUpdate.Result#LOCK_FAILURE} should be retried, otherwise
+   *         {@link Result#LOCK_FAILURE} should be retried, otherwise
    *         <code>false</code>
    */
   public boolean retryOnLockFailure() {

gerrit-server/src/main/java/com/google/gerrit/server/query/Predicate.java

@@ -40,7 +40,7 @@ import java.util.List;
  * other predicates should override {@link #getChildren()} to return the list of
  * children nested within the predicate.
  *
- * @type <T> type of object the predicate can evaluate in memory.
+ * @param <T> type of object the predicate can evaluate in memory.
  */
 public abstract class Predicate<T> {
   /** A predicate that matches any input, always, with no cost. */

gerrit-server/src/main/java/com/google/gerrit/server/query/QueryRewriter.java

@@ -51,7 +51,7 @@ import java.util.Map;
  * Rewrite methods are applied in order by declared name, so naming methods with
  * a numeric prefix to ensure a specific ordering (if required) is suggested.
  *
- * @type <T> type of object the predicate can evaluate in memory.
+ * @param <T> type of object the predicate can evaluate in memory.
  */
 public abstract class QueryRewriter<T> {
   /**

gerrit-server/src/main/java/com/google/gerrit/server/query/change/ChangeStatusPredicate.java

@@ -18,6 +18,7 @@ import static com.google.common.base.Preconditions.checkArgument;
 
 import com.google.common.collect.ImmutableBiMap;
 import com.google.gerrit.reviewdb.client.Change;
+import com.google.gerrit.reviewdb.client.Change.Status;
 import com.google.gerrit.reviewdb.server.ReviewDb;
 import com.google.gerrit.server.index.ChangeField;
 import com.google.gerrit.server.index.IndexPredicate;
@@ -29,7 +30,7 @@ import java.util.ArrayList;
 import java.util.List;
 
 /**
- * Predicate for a {@link Change.Status}.
+ * Predicate for a {@link Status}.
  * <p>
  * The actual name of this operator can differ, it usually comes as {@code
  * status:} but may also be {@code is:} to help do-what-i-meanery for end-users

lib/guice/BUCK

@@ -58,7 +58,7 @@ maven_jar(
     'javax/annotation/WillCloseWhenClosed.java',
     'javax/annotation/WillNotClose.java',
   ],
-  visibility = [],
+  visibility = ['PUBLIC'],
 )
 
 maven_jar(
@@ -92,5 +92,5 @@ maven_jar(
   id = 'javax.inject:javax.inject:1',
   sha1 = '6975da39a7040257bd51d21a231b76c915872d38',
   license = 'Apache2.0',
-  visibility = ['//lib/guice:guice'],
+  visibility = ['PUBLIC'],
 )

tools/default.defs

@@ -206,3 +206,36 @@ def java_sources(
     resources = srcs,
     visibility = visibility,
   )
+
+def java_doc(
+    name,
+    title,
+    pkg,
+    paths,
+    srcs = [],
+    deps = [],
+    visibility = []
+  ):
+  genrule(
+    name = name,
+    cmd = ' '.join([
+      'javadoc',
+      '-quiet',
+      '-protected',
+      '-encoding UTF-8',
+      '-charset UTF-8',
+      '-notimestamp',
+      '-windowtitle "' + title + '"',
+      '-link http://docs.oracle.com/javase/7/docs/api',
+      '-subpackages ' + pkg,
+      '-sourcepath ',
+      ':'.join([n for n in paths]),
+      ' -classpath ',
+      ':'.join(['$(location %s)' % n for n in deps]),
+      '-d $TMP',
+    ]) + ';jar cf $OUT -C $TMP .',
+    srcs = srcs,
+    deps = deps,
+    out = name + '.jar',
+    visibility = visibility,
+)

tools/maven/BUCK

@@ -8,14 +8,19 @@ maven_package(
   url = 's3://gerrit-api@commondatastorage.googleapis.com/%s' % TYPE,
   version = GERRIT_VERSION,
   jar = {
-    'gerrit-extension-api': '//:extension-api',
-    'gerrit-plugin-api': '//:plugin-api',
-    'gerrit-plugin-gwtui': '//:plugin-gwtui',
+    'gerrit-extension-api': '//gerrit-extension-api:extension-api',
+    'gerrit-plugin-api': '//gerrit-plugin-api:plugin-api',
+    'gerrit-plugin-gwtui': '//gerrit-plugin-gwtui:gwtui-api',
   },
   src = {
-    'gerrit-extension-api': '//:extension-api-src',
-    'gerrit-plugin-api': '//:plugin-api-src',
-    'gerrit-plugin-gwtui': '//:plugin-gwtui-src',
+    'gerrit-extension-api': '//gerrit-extension-api:extension-api-src',
+    'gerrit-plugin-api': '//gerrit-plugin-api:plugin-api-src',
+    'gerrit-plugin-gwtui': '//gerrit-plugin-gwtui:gwtui-api-src',
+  },
+  doc = {
+    'gerrit-extension-api': '//gerrit-extension-api:extension-api-javadoc',
+    'gerrit-plugin-api': '//gerrit-plugin-api:plugin-api-javadoc',
+    'gerrit-plugin-gwtui': '//gerrit-plugin-gwtui:gwtui-api-javadoc',
   },
 )
 

tools/maven/package.defs

@@ -17,11 +17,12 @@ def maven_package(
     repository = None,
     url = None,
     jar = {},
-    src = {}):
+    src = {},
+    doc = {}):
   cmd = ['$(exe //tools/maven:mvn)', '-v', version, '-o', '$OUT']
   dep = []
 
-  for type,d in [('jar', jar), ('java-source', src)]:
+  for type,d in [('jar', jar), ('java-source', src), ('javadoc', doc)]:
     for a,t in d.iteritems():
       cmd.append('-s %s:%s:$(location %s)' % (a,type,t))
       dep.append(t)