Javadoc improvements. Fixes #71.

45 files changed, 778 insertions, 91 deletions

diff --git a/CHANGELOG-3.7.md b/CHANGELOG-3.7.md
index 91f3c6e24ee..d4d74c927c5 100644
--- a/CHANGELOG-3.7.md
+++ b/CHANGELOG-3.7.md
@@ -70,6 +70,13 @@ These are the changes since Ice 3.7.1 included in this pre-release.
 - Fixed metrics bug where remote invocations for flushBatchRequests weren't
   counted.
 
+- Improved Javadoc support for the Java mapping (and not Java-Compat). Internal
+  classes and methods with public or protected visibility are now excluded or
+  tagged `@hidden`. Since `@hidden` requires javadoc 9 or greater, javadoc is no
+  longer generated with javadoc 8.
+  The new Gradle target `alljavadoc` generates a complete API reference for all Ice
+  components (Ice, IceSSL, IceGrid, IceStorm, Glacier2, etc.).
+
 ## JavaScript Changes
 
 - Added TypeScript declaration files for Ice for JavaScript.
diff --git a/cpp/src/slice2java/Gen.cpp b/cpp/src/slice2java/Gen.cpp
index facca46c385..426f7dbd7ce 100644
--- a/cpp/src/slice2java/Gen.cpp
+++ b/cpp/src/slice2java/Gen.cpp
@@ -18,17 +18,6 @@
 
 #include <limits>
 
-// TODO: fix this warning!
-#if defined(_MSC_VER)
-#   pragma warning(disable:4456) // shadow
-#   pragma warning(disable:4457) // shadow
-#   pragma warning(disable:4459) // shadow
-#elif defined(__clang__)
-#   pragma clang diagnostic ignored "-Wshadow"
-#elif defined(__GNUC__)
-#   pragma GCC diagnostic ignored "-Wshadow"
-#endif
-
 using namespace std;
 using namespace Slice;
 using namespace IceUtil;
@@ -236,7 +225,9 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
     string opName = op->name();
     opName[0] = static_cast<char>(toupper(static_cast<unsigned char>(opName[0])));
 
-    out << sp << nl << "public static class " << opName << "Result";
+    out << sp;
+    writeDocComment(out, "Holds the result of operation " + op->name() + ".");
+    out << nl << "public static class " << opName << "Result";
     out << sb;
 
     //
@@ -260,6 +251,7 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
     //
     // Default constructor.
     //
+    writeDocComment(out, "Default constructor.");
     out << nl << "public " << opName << "Result()";
     out << sb;
     out << eb;
@@ -515,7 +507,9 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op
     assert(cl);
     opName[0] = static_cast<char>(toupper(static_cast<unsigned char>(opName[0])));
 
-    out << sp << nl << "public static class " << opName << "MarshaledResult implements "
+    out << sp;
+    writeDocComment(out, "Holds the marshaled result of operation " + op->name() + ".");
+    out << nl << "public static class " << opName << "MarshaledResult implements "
         << getUnqualified("com.zeroc.Ice.MarshaledResult", package) << sb;
 
     const ParamDeclList outParams = op->outParameters();
@@ -531,7 +525,7 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op
     if(dc)
     {
         out << nl << "/**";
-        out << nl << " * This constructor marshals the results of operation " << opName << " immediately.";
+        out << nl << " * This constructor marshals the results of operation " << op->name() << " immediately.";
 
         if(ret && !dc->returns().empty())
         {
@@ -634,7 +628,7 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op
         if(dc)
         {
             out << nl << "/**";
-            out << nl << " * This constructor marshals the results of operation " << opName
+            out << nl << " * This constructor marshals the results of operation " << op->name()
                 << " immediately (overload without Optional parameters).";
 
             if(ret && !dc->returns().empty())
@@ -1168,7 +1162,9 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
     assert(scopedIter != ids.end());
 #endif
 
-    out << sp << nl << "static final String[] _iceIds =";
+    out << sp;
+    writeHiddenDocComment(out);
+    out << nl << "static final String[] _iceIds =";
     out << sb;
 
     for(StringList::const_iterator q = ids.begin(); q != ids.end();)
@@ -1220,6 +1216,18 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
 
         string opName = op->name();
         out << sp;
+
+        out << nl << "/**";
+        out << nl << " * @hidden";
+        out << nl << " * @param obj -";
+        out << nl << " * @param inS -";
+        out << nl << " * @param current -";
+        out << nl << " * @return -";
+        if(!op->throws().empty() || op->hasMetaData("java:UserException") || op->hasMetaData("UserException"))
+        {
+            out << nl << " * @throws " << getUnqualified("com.zeroc.Ice.UserException", package) << " -";
+        }
+        out << nl << "**/";
         if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
@@ -1393,7 +1401,9 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
         allOpNames.sort();
         allOpNames.unique();
 
-        out << sp << nl << "final static String[] _iceOps =";
+        out << sp;
+        writeHiddenDocComment(out);
+        out << nl << "final static String[] _iceOps =";
         out << sb;
         for(StringList::const_iterator q = allOpNames.begin(); q != allOpNames.end();)
         {
@@ -1406,6 +1416,7 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
         out << eb << ';';
 
         out << sp;
+        writeHiddenDocComment(out);
         for(OperationList::iterator r = allOps.begin(); r != allOps.end(); ++r)
         {
             //
@@ -1483,16 +1494,16 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
                         }
                         else
                         {
-                            string base;
+                            string baseName;
                             if(cl->isInterface())
                             {
-                                base = getUnqualified(cl, package);
+                                baseName = getUnqualified(cl, package);
                             }
                             else
                             {
-                                base = getUnqualified(cl, package, "", "Disp");
+                                baseName = getUnqualified(cl, package, "", "Disp");
                             }
-                            out << nl << "return " << base << "._iceD_" << opName << "(this, in, current);";
+                            out << nl << "return " << baseName << "._iceD_" << opName << "(this, in, current);";
                         }
                         break;
                     }
@@ -1530,6 +1541,7 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
     if(preserved && !basePreserved)
     {
         out << sp;
+        writeHiddenDocComment(out);
         out << nl << "@Override";
         out << nl << "public " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " ice_getSlicedData()";
         out << sb;
@@ -1537,6 +1549,7 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
         out << eb;
 
         out << sp;
+        writeHiddenDocComment(out);
         out << nl << "@Override";
         out << nl << "public void _iceWrite(" << getUnqualified("com.zeroc.Ice.OutputStream", package) << " ostr)";
         out << sb;
@@ -1546,6 +1559,7 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
         out << eb;
 
         out << sp;
+        writeHiddenDocComment(out);
         out << nl << "@Override";
         out << nl << "public void _iceRead(" << getUnqualified("com.zeroc.Ice.InputStream", package) << " istr)";
         out << sb;
@@ -1556,6 +1570,7 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
     }
 
     out << sp;
+    writeHiddenDocComment(out);
     out << nl << "@Override";
     out << nl << "protected void _iceWriteImpl(" << getUnqualified("com.zeroc.Ice.OutputStream", package) << " ostr_)";
     out << sb;
@@ -1583,6 +1598,7 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
     DataMemberList allClassMembers = p->allClassDataMembers();
 
     out << sp;
+    writeHiddenDocComment(out);
     out << nl << "@Override";
     out << nl << "protected void _iceReadImpl(" << getUnqualified("com.zeroc.Ice.InputStream", package) << " istr_)";
     out << sb;
@@ -1610,7 +1626,9 @@ Slice::JavaVisitor::writeMarshaling(Output& out, const ClassDefPtr& p)
 
     if(preserved && !basePreserved)
     {
-        out << sp << nl << "protected " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " _iceSlicedData;";
+        out << sp;
+        writeHiddenDocComment(out);
+        out << nl << "protected " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " _iceSlicedData;";
     }
 }
 
@@ -1754,6 +1772,12 @@ Slice::JavaVisitor::splitComment(const ContainedPtr& p)
 }
 
 void
+Slice::JavaVisitor::writeHiddenDocComment(Output& out)
+{
+    out << nl << "/** @hidden */";
+}
+
+void
 Slice::JavaVisitor::writeDocCommentLines(Output& out, const StringList& lines)
 {
     //
@@ -1825,7 +1849,7 @@ Slice::JavaVisitor::writeDocCommentLines(Output& out, const string& text)
 }
 
 void
-Slice::JavaVisitor::writeDocComment(Output& out, const UnitPtr& unit, const CommentPtr& dc)
+Slice::JavaVisitor::writeDocComment(Output& out, const UnitPtr& unt, const CommentPtr& dc)
 {
     if(!dc)
     {
@@ -1852,7 +1876,7 @@ Slice::JavaVisitor::writeDocComment(Output& out, const UnitPtr& unit, const Comm
         for(StringList::iterator p = sa.begin(); p != sa.end(); ++p)
         {
             out << nl << " * @see ";
-            writeSeeAlso(out, unit, *p);
+            writeSeeAlso(out, unt, *p);
         }
     }
 
@@ -1883,14 +1907,13 @@ Slice::JavaVisitor::writeDocComment(Output& out, const string& text)
 
 void
 Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, const string& package,
-                                         const CommentPtr& dc, bool async, bool context)
+                                         const CommentPtr& dc, bool async, const string& contextParam)
 {
     if(!dc)
     {
         return;
     }
 
-    const string contextParam = " * @param context The Context map to send with the invocation.";
     map<string, StringList> paramDocs = dc->parameters();
 
     out << nl << "/**";
@@ -1914,9 +1937,9 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
             writeDocCommentLines(out, j->second);
         }
     }
-    if(context)
+    if(!contextParam.empty())
     {
-        out << nl << contextParam;
+        out << nl << " * " << contextParam;
     }
 
     //
@@ -2013,6 +2036,35 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
 }
 
 void
+Slice::JavaVisitor::writeHiddenProxyDocComment(Output& out, const OperationPtr& p)
+{
+    // the _iceI_ methods are all async
+
+    out << nl << "/**";
+    out << nl << " * @hidden";
+
+    //
+    // Show in-params in order of declaration
+    //
+    const ParamDeclList paramList = p->inParameters();
+    for(ParamDeclList::const_iterator i = paramList.begin(); i != paramList.end(); ++i)
+    {
+        const string name = (*i)->name();
+        out << nl << " * @param " << "iceP_" << name << " -";
+    }
+    out << nl << " * @param context -";
+    out << nl << " * @param sync -";
+
+    //
+    // There is always a return value since it's async
+    //
+    out << nl << " * @return -";
+
+    // No throws since it's async
+    out << nl << " **/";
+}
+
+void
 Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, const string& package,
                                            const CommentPtr& dc, bool async)
 {
@@ -2144,7 +2196,7 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c
 }
 
 void
-Slice::JavaVisitor::writeSeeAlso(Output& out, const UnitPtr& unit, const string& ref)
+Slice::JavaVisitor::writeSeeAlso(Output& out, const UnitPtr& unt, const string& ref)
 {
     assert(!ref.empty());
 
@@ -2175,7 +2227,7 @@ Slice::JavaVisitor::writeSeeAlso(Output& out, const UnitPtr& unit, const string&
         s.insert(0, "::");
     }
 
-    TypeList l = unit->lookupTypeNoBuiltin(s, false, true);
+    TypeList l = unt->lookupTypeNoBuiltin(s, false, true);
     if(l.empty())
     {
         out << ref;
@@ -2256,7 +2308,9 @@ Slice::Gen::writeChecksumClass(const string& checksumClass, const string& dir, c
     //
     // Emit the class.
     //
-    out << sp << nl << "public class " << className;
+    out << sp;
+    out << nl << "/** @hidden */";
+    out << nl << "public class " << className;
     out << sb;
 
     //
@@ -2656,12 +2710,14 @@ Slice::Gen::TypesVisitor::visitClassDefEnd(const ClassDefPtr& p)
 
     if(!p->isInterface())
     {
-        out << sp << nl << "public static final long serialVersionUID = ";
+        out << sp;
+        writeHiddenDocComment(out);
+        out << nl << "public static final long serialVersionUID = ";
         string serialVersionUID;
         if(p->findMetaData("java:serialVersionUID", serialVersionUID))
         {
-            const UnitPtr unit = p->unit();
-            const DefinitionContextPtr dc = unit->findDefinitionContext(p->file());
+            const UnitPtr unt = p->unit();
+            const DefinitionContextPtr dc = unt->findDefinitionContext(p->file());
             assert(dc);
 
             string::size_type pos = serialVersionUID.rfind(":") + 1;
@@ -2757,7 +2813,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p)
         throws.unique();
         out << sp;
 
-        writeProxyDocComment(out, p, package, dc, false, false);
+        writeProxyDocComment(out, p, package, dc, false, "");
         if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
@@ -2777,7 +2833,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p)
         if(cl->hasMetaData("async-oneway") || p->hasMetaData("async-oneway"))
         {
             out << sp;
-            writeProxyDocComment(out, p, package, dc, true, false);
+            writeProxyDocComment(out, p, package, dc, true, "");
             if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
@@ -2998,8 +3054,8 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
             {
                 out << nl << "super" << spar;
                 vector<string> baseParamNames;
-                DataMemberList baseDataMembers = base->allDataMembers();
-                for(DataMemberList::const_iterator d = baseDataMembers.begin(); d != baseDataMembers.end(); ++d)
+                DataMemberList baseDataMemberList = base->allDataMembers();
+                for(DataMemberList::const_iterator d = baseDataMemberList.begin(); d != baseDataMemberList.end(); ++d)
                 {
                     baseParamNames.push_back(fixKwd((*d)->name()));
                 }
@@ -3041,8 +3097,8 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
                 {
                     out << nl << "super" << spar;
                     vector<string> baseParamNames;
-                    DataMemberList baseDataMembers = base->allDataMembers();
-                    for(DataMemberList::const_iterator d = baseDataMembers.begin(); d != baseDataMembers.end(); ++d)
+                    DataMemberList baseDataMemberList = base->allDataMembers();
+                    for(DataMemberList::const_iterator d = baseDataMemberList.begin(); d != baseDataMemberList.end(); ++d)
                     {
                         baseParamNames.push_back(fixKwd((*d)->name()));
                     }
@@ -3097,6 +3153,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         if(preserved && !basePreserved)
         {
             out << sp;
+            writeHiddenDocComment(out);
             out << nl << "@Override";
             out << nl << "public " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " ice_getSlicedData()";
             out << sb;
@@ -3104,6 +3161,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             out << eb;
 
             out << sp;
+            writeHiddenDocComment(out);
             out << nl << "@Override";
             out << nl << "public void _write(" << getUnqualified("com.zeroc.Ice.OutputStream", package) << " ostr)";
             out << sb;
@@ -3113,6 +3171,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             out << eb;
 
             out << sp;
+            writeHiddenDocComment(out);
             out << nl << "@Override";
             out << nl << "public void _read(" << getUnqualified("com.zeroc.Ice.InputStream", package) << " istr)";
             out << sb;
@@ -3123,6 +3182,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         }
 
         out << sp;
+        writeHiddenDocComment(out);
         out << nl << "@Override";
         out << nl << "protected void _writeImpl(" << getUnqualified("com.zeroc.Ice.OutputStream", package) << " ostr_)";
         out << sb;
@@ -3150,6 +3210,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         DataMemberList allClassMembers = p->allClassDataMembers();
 
         out << sp;
+        writeHiddenDocComment(out);
         out << nl << "@Override";
         out << nl << "protected void _readImpl(" << getUnqualified("com.zeroc.Ice.InputStream", package) << " istr_)";
         out << sb;
@@ -3178,6 +3239,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             if(!base || (base && !base->usesClasses(false)))
             {
                 out << sp;
+                writeHiddenDocComment(out);
                 out << nl << "@Override";
                 out << nl << "public boolean _usesClasses()";
                 out << sb;
@@ -3188,16 +3250,20 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
 
         if(preserved && !basePreserved)
         {
-            out << sp << nl << "protected " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " _slicedData;";
+            out << sp;
+            writeHiddenDocComment(out);
+            out << nl << "protected " << getUnqualified("com.zeroc.Ice.SlicedData", package) << " _slicedData;";
         }
     }
 
-    out << sp << nl << "public static final long serialVersionUID = ";
+    out << sp;
+    writeHiddenDocComment(out);
+    out << nl << "public static final long serialVersionUID = ";
     string serialVersionUID;
     if(p->findMetaData("java:serialVersionUID", serialVersionUID))
     {
-        const UnitPtr unit = p->unit();
-        const DefinitionContextPtr dc = unit->findDefinitionContext(p->file());
+        const UnitPtr unt = p->unit();
+        const DefinitionContextPtr dc = unt->findDefinitionContext(p->file());
         assert(dc);
 
         string::size_type pos = serialVersionUID.rfind(":") + 1;
@@ -3564,12 +3630,14 @@ Slice::Gen::TypesVisitor::visitStructEnd(const StructPtr& p)
         out << sp << nl << "private static final " << name << " _nullMarshalValue = new " << name << "();";
     }
 
-    out << sp << nl << "public static final long serialVersionUID = ";
+    out << sp;
+    writeHiddenDocComment(out);
+    out << nl << "public static final long serialVersionUID = ";
     string serialVersionUID;
     if(p->findMetaData("java:serialVersionUID", serialVersionUID))
     {
-        const UnitPtr unit = p->unit();
-        const DefinitionContextPtr dc = unit->findDefinitionContext(p->file());
+        const UnitPtr unt = p->unit();
+        const DefinitionContextPtr dc = unt->findDefinitionContext(p->file());
         assert(dc);
         string::size_type pos = serialVersionUID.rfind(":") + 1;
         if(pos == string::npos)
@@ -4174,7 +4242,9 @@ Slice::Gen::CompactIdVisitor::visitClassDefStart(const ClassDefPtr& p)
         open(os.str(), p->file());
 
         Output& out = output();
-        out << sp << nl << "public class TypeId_" << p->compactId();
+        out << sp;
+        writeHiddenDocComment(out);
+        out << nl << "public class TypeId_" << p->compactId();
         out << sb;
         out << nl << "public final static String typeId = \"" << p->scoped() << "\";";
         out << eb;
@@ -4273,7 +4343,9 @@ Slice::Gen::HelperVisitor::visitSequence(const SequencePtr& p)
 
     int iter;
 
-    out << sp << nl << "public final class " << name << "Helper";
+    out << sp;
+    writeDocComment(out, "Helper class for marshaling/unmarshaling " + name + ".");
+    out << nl << "public final class " << name << "Helper";
     out << sb;
 
     out << nl << "public static void write(" << getUnqualified("com.zeroc.Ice.OutputStream", package)
@@ -4427,6 +4499,7 @@ Slice::Gen::HelperVisitor::visitDictionary(const DictionaryPtr& p)
 
     int iter;
 
+    writeDocComment(out, "Helper class for marshaling/unmarshaling " + name + ".");
     out << sp << nl << "public final class " << name << "Helper";
     out << sb;
 
@@ -4938,6 +5011,7 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
     Output& outi = output();
 
     outi << sp;
+    writeHiddenDocComment(outi);
     if(dc && dc->isDeprecated())
     {
         outi << nl << "@Deprecated";
@@ -4945,7 +5019,9 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
     outi << nl << "public class _" << p->name() << "PrxI extends " << getUnqualified("com.zeroc.Ice._ObjectPrxI", package)
          << " implements " << p->name() << "Prx";
     outi << sb;
-    outi << sp << nl << "public static final long serialVersionUID = 0L;";
+    outi << sp;
+    writeHiddenDocComment(outi);
+    outi << nl << "public static final long serialVersionUID = 0L;";
     outi << eb;
     close();
 }
@@ -4999,7 +5075,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     // Synchronous methods with required parameters.
     //
     out << sp;
-    writeProxyDocComment(out, p, package, dc, false, false);
+    writeProxyDocComment(out, p, package, dc, false, "");
     if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
@@ -5016,7 +5092,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     out << eb;
 
     out << sp;
-    writeProxyDocComment(out, p, package, dc, false, true);
+    writeProxyDocComment(out, p, package, dc, false, contextDoc);
     if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
@@ -5065,7 +5141,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     if(sendsOptionals)
     {
         out << sp;
-        writeProxyDocComment(out, p, package, dc, false, false);
+        writeProxyDocComment(out, p, package, dc, false, "");
         if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
@@ -5082,7 +5158,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         out << eb;
 
         out << sp;
-        writeProxyDocComment(out, p, package, dc, false, true);
+        writeProxyDocComment(out, p, package, dc, false, contextDoc);
         if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
@@ -5131,28 +5207,27 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     // Asynchronous methods with required parameters.
     //
     out << sp;
-    writeProxyDocComment(out, p, package, dc, true, false);
+    writeProxyDocComment(out, p, package, dc, true, "");
 
-    const string future = getFutureType(p, package);
+    const string futureType = getFutureType(p, package);
 
     if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
-    out << nl << "default " << future << ' ' << p->name() << "Async" << spar << params << epar;
+    out << nl << "default " << futureType << ' ' << p->name() << "Async" << spar << params << epar;
     out << sb;
     out << nl << "return _iceI_" << p->name() << "Async" << spar << args << noExplicitContextArg << "false" << epar
         << ';';
     out << eb;
 
     out << sp;
-    writeProxyDocComment(out, p, package, dc, true, true);
-
+    writeProxyDocComment(out, p, package, dc, true, contextDoc);
     if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
-    out << nl << "default " << future << ' ' << p->name() << "Async" << spar << params << contextParam << epar;
+    out << nl << "default " << futureType << ' ' << p->name() << "Async" << spar << params << contextParam << epar;
     out << sb;
     out << nl << "return _iceI_" << p->name() << "Async" << spar << args << contextParamName << "false" << epar << ';';
     out << eb;
@@ -5160,6 +5235,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     const string futureImpl = getFutureImplType(p, package);
 
     out << sp;
+    writeHiddenProxyDocComment(out, p);
     out << nl << "default " << futureImpl << " _iceI_" << p->name() << "Async" << spar << getParamsProxy(p, package, false, true)
         << "java.util.Map<String, String> context"
         << "boolean sync" << epar;
@@ -5204,7 +5280,9 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
     if(!throws.empty())
     {
-        out << sp << nl << "static final Class<?>[] _iceE_" << p->name() << " =";
+        out << sp;
+        writeHiddenDocComment(out);
+        out << nl << "static final Class<?>[] _iceE_" << p->name() << " =";
         out << sb;
         for(ExceptionList::const_iterator t = throws.begin(); t != throws.end(); ++t)
         {
@@ -5220,7 +5298,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     if(sendsOptionals)
     {
         out << sp;
-        writeProxyDocComment(out, p, package, dc, true, false);
+        writeProxyDocComment(out, p, package, dc, true, "");
 
         const string future = getFutureType(p, package);
 
@@ -5235,7 +5313,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         out << eb;
 
         out << sp;
-        writeProxyDocComment(out, p, package, dc, true, true);
+        writeProxyDocComment(out, p, package, dc, true, contextDoc);
 
         if(dc && dc->isDeprecated())
         {
@@ -5247,6 +5325,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         out << eb;
 
         out << sp;
+        writeHiddenProxyDocComment(out, p);
         out << nl << "default " << futureImpl << " _iceI_" << p->name() << "Async" << spar << getParamsProxy(p, package, true, true)
             << "java.util.Map<String, String> context"
             << "boolean sync" << epar;
diff --git a/cpp/src/slice2java/Gen.h b/cpp/src/slice2java/Gen.h
index d4bfbd8c0c0..c21769a59d8 100644
--- a/cpp/src/slice2java/Gen.h
+++ b/cpp/src/slice2java/Gen.h
@@ -100,12 +100,14 @@ protected:
     // Handle doc comments.
     //
     static StringList splitComment(const ContainedPtr&);
+    void writeHiddenDocComment(::IceUtilInternal::Output&);
     void writeDocCommentLines(::IceUtilInternal::Output&, const StringList&);
     void writeDocCommentLines(::IceUtilInternal::Output&, const std::string&);
     void writeDocComment(::IceUtilInternal::Output&, const UnitPtr&, const CommentPtr&);
     void writeDocComment(::IceUtilInternal::Output&, const std::string&);
     void writeProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const CommentPtr&,
-                              bool, bool);
+                              bool, const std::string&);
+    void writeHiddenProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&);
     void writeServantDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&,
                                 const CommentPtr&, bool);
     void writeSeeAlso(::IceUtilInternal::Output&, const UnitPtr&, const std::string&);
diff --git a/cpp/src/slice2java/Main.cpp b/cpp/src/slice2java/Main.cpp
index 48f6c8916ba..2150bf92dd0 100644
--- a/cpp/src/slice2java/Main.cpp
+++ b/cpp/src/slice2java/Main.cpp
@@ -23,17 +23,6 @@ using namespace std;
 using namespace Slice;
 using namespace IceUtilInternal;
 
-// TODO: fix this warning!
-#if defined(_MSC_VER)
-#   pragma warning(disable:4456) // shadow
-#   pragma warning(disable:4457) // shadow
-#   pragma warning(disable:4459) // shadow
-#elif defined(__clang__)
-#   pragma clang diagnostic ignored "-Wshadow"
-#elif defined(__GNUC__)
-#   pragma GCC diagnostic ignored "-Wshadow"
-#endif
-
 namespace
 {
 
@@ -274,8 +263,8 @@ compile(const vector<string>& argv)
         //
         // Ignore duplicates.
         //
-        vector<string>::iterator p = find(args.begin(), args.end(), *i);
-        if(p != i)
+        vector<string>::iterator j = find(args.begin(), args.end(), *i);
+        if(j != i)
         {
             continue;
         }
@@ -312,7 +301,6 @@ compile(const vector<string>& argv)
         }
         else
         {
-            ostringstream os;
             FileTracker::instance()->setSource(*i);
 
             PreprocessorPtr icecpp = Preprocessor::create(argv[0], *i, cppArgs);
diff --git a/java/build.gradle b/java/build.gradle
index 957bde22764..fa4bc8826d5 100644
--- a/java/build.gradle
+++ b/java/build.gradle
@@ -58,6 +58,43 @@ subprojects {
     }
 }
 
+def exportedProjects = [
+    ":glacier2",
+    ":ice",
+    ":icebox",
+    ":icebt",
+    ":icegrid",
+    ":icepatch2",
+    "::icessl",
+    ":icestorm"
+    ]
+
+task alljavadoc(type: Javadoc) {
+
+    // We rely on Java9+ javadoc features
+    enabled = JavaVersion.current() > JavaVersion.VERSION_1_8
+
+    source exportedProjects.collect { project(it).javadoc.source }
+    classpath = files(exportedProjects.collect { project(it).javadoc.classpath })
+    destinationDir = file("${buildDir}/docs/javadoc")
+
+    if(JavaVersion.current() >= JavaVersion.VERSION_11) {
+        // TODO: --no-module-directories is an undocumented option required for the
+        // generated search to work properly. Without this option, search returns
+        // .../undefined/... URLs.
+        options.addBooleanOption('-no-module-directories', true)
+    }
+    options.addBooleanOption('html5', true)
+    options.header = 'Ice for Java'
+    options.docTitle = "Ice ${iceVersion} API Reference"
+}
+
+alljavadoc.dependsOn = exportedProjects.collect { project(it).javadoc.dependsOn }
+
+task clean(type: Delete) {
+    delete rootProject.buildDir
+}
+
 task dist()
 dist.dependsOn(project(":ice").assemble)
 dist.dependsOn(project(":icessl").assemble)
diff --git a/java/gradle/library.gradle b/java/gradle/library.gradle
index d697be1b1a3..02dd1c039f2 100644
--- a/java/gradle/library.gradle
+++ b/java/gradle/library.gradle
@@ -71,13 +71,22 @@ task jarSources(type:Jar, dependsOn: jar){
 
 assemble.dependsOn(jarSources)
 
+javadoc.dependsOn(compileSlice)
+
 javadoc {
-    failOnError = false
+    // We rely on Java9+ javadoc features
+    enabled = JavaVersion.current() > JavaVersion.VERSION_1_8
+
+    failOnError = true
     options.header = project.ext.displayName
-    if(JavaVersion.current() > JavaVersion.VERSION_1_8) {
-        // Add -quiet to workaround Gradle bug https://github.com/gradle/gradle/issues/2354
-        options.addStringOption("html4", "-quiet")
+
+    if(JavaVersion.current() >= JavaVersion.VERSION_11) {
+        // TODO: --no-module-directories is an undocumented option required for the
+        // generated search to work properly. Without this option, search returns
+        // .../undefined/... URLs.
+        options.addBooleanOption('-no-module-directories', true)
     }
+    options.addBooleanOption('html5', true)
     classpath = project.sourceSets.main.compileClasspath
 }
 
diff --git a/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/package-info.java b/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/package-info.java
new file mode 100644
index 00000000000..8c301b7bf68
--- /dev/null
+++ b/java/src/Glacier2/src/main/java/com/zeroc/Glacier2/package-info.java
@@ -0,0 +1,13 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for clients of the Glacier2 firewall traversal service.
+ **/
+package com.zeroc.Glacier2;
diff --git a/java/src/Ice/build.gradle b/java/src/Ice/build.gradle
index 3ec55f70b14..6c08c15e650 100644
--- a/java/src/Ice/build.gradle
+++ b/java/src/Ice/build.gradle
@@ -27,3 +27,17 @@ slice {
 }
 
 apply from: "$project.ext.topSrcDir/java/gradle/library.gradle"
+
+//
+// Unfortunately we can't simply process Ice classes through javadoc as
+// they use various public IceInternal and IceUtilInternal classes. So
+// we first compile everything then use these compiled classes to javadoc
+// the code we want to document. A handful of public Ice classes (other
+// than the *I.java classes) are also marked @hidden.
+//
+javadoc.dependsOn(compileJava)
+
+javadoc {
+    classpath = project.sourceSets.main.output
+    excludes = ["**/IceInternal/*.java", "**/IceUtilInternal/*.java", "**/Ice/*I.java"]
+}
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/Application.java b/java/src/Ice/src/main/java/com/zeroc/Ice/Application.java
index 775a5523f44..c677c66ee91 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/Application.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/Application.java
@@ -564,6 +564,7 @@ public abstract class Application
     }
 
     // For use by Glacier2.Application
+    /** @hidden */
     static public class AppHook extends Thread
     {
         public void
@@ -687,12 +688,27 @@ public abstract class Application
         private Runnable _hook;
     }
 
+    /** @hidden */
     protected static String _appName;
+
+    /** @hidden */
     protected static Communicator _communicator;
+
+    /** @hidden */
     protected static AppHook _appHook;
+
+    /** @hidden */
     protected final static java.lang.Object _mutex = new java.lang.Object();
+
+    /** @hidden */
     protected static boolean _callbackInProgress = false;
+
+    /** @hidden */
     protected static boolean _destroyed = false;
+
+    /** @hidden */
     protected static boolean _interrupted = false;
+
+    /** @hidden */
     protected static SignalPolicy _signalPolicy = SignalPolicy.HandleSignals;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/BatchRequest.java b/java/src/Ice/src/main/java/com/zeroc/Ice/BatchRequest.java
index d064751965e..9db6e110aa3 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/BatchRequest.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/BatchRequest.java
@@ -9,6 +9,9 @@
 
 package com.zeroc.Ice;
 
+/**
+ * Represents an invocation on a proxy configured for batch-oneway or batch-datagram.
+ **/
 public interface BatchRequest
 {
     /**
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/Blobject.java b/java/src/Ice/src/main/java/com/zeroc/Ice/Blobject.java
index ce7d7097e34..e8e52cab81d 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/Blobject.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/Blobject.java
@@ -37,6 +37,7 @@ public interface Blobject extends com.zeroc.Ice.Object
     com.zeroc.Ice.Object.Ice_invokeResult ice_invoke(byte[] inEncaps, Current current)
         throws UserException;
 
+    /** @hidden */
     @Override
     default CompletionStage<OutputStream> _iceDispatch(com.zeroc.IceInternal.Incoming in, Current current)
         throws UserException
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/BlobjectAsync.java b/java/src/Ice/src/main/java/com/zeroc/Ice/BlobjectAsync.java
index 43f13e42fb2..67f71a4e527 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/BlobjectAsync.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/BlobjectAsync.java
@@ -43,6 +43,7 @@ public interface BlobjectAsync extends com.zeroc.Ice.Object
     CompletionStage<Object.Ice_invokeResult> ice_invokeAsync(byte[] inEncaps, Current current)
         throws UserException;
 
+    /** @hidden */
     @Override
     default CompletionStage<OutputStream> _iceDispatch(com.zeroc.IceInternal.Incoming in, Current current)
         throws UserException
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/DispatchInterceptor.java b/java/src/Ice/src/main/java/com/zeroc/Ice/DispatchInterceptor.java
index dc30d3fa6e2..a9fe259e8d0 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/DispatchInterceptor.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/DispatchInterceptor.java
@@ -36,6 +36,7 @@ public abstract class DispatchInterceptor implements com.zeroc.Ice.Object
     public abstract CompletionStage<OutputStream> dispatch(Request request)
         throws UserException;
 
+    /** @hidden */
     @Override
     public CompletionStage<OutputStream> _iceDispatch(com.zeroc.IceInternal.Incoming in, Current current)
         throws UserException
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
index bcacb2dfe33..4af6261e1e1 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/InputStream.java
@@ -16,8 +16,8 @@ import com.zeroc.IceInternal.Instance;
 import com.zeroc.IceInternal.Protocol;
 
 /**
- * Interface for input streams used to extract Slice types from a sequence
- * of bytes.
+ * Interface to read sequence of bytes encoded using the Ice encoding and
+ * recreate the corresponding Slice types.
  *
  * @see OutputStream
  **/
@@ -3549,6 +3549,7 @@ public class InputStream
         }
     }
 
+    /** @hidden */
     @FunctionalInterface
     static public interface Unmarshaler
     {
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/Instrumentation/package-info.java b/java/src/Ice/src/main/java/com/zeroc/Ice/Instrumentation/package-info.java
new file mode 100644
index 00000000000..c4b0d735532
--- /dev/null
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/Instrumentation/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * Ice Instrumentation API, used to observe Ice internal components such as
+ * threads and connections.
+ **/
+package com.zeroc.Ice.Instrumentation;
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/InterfaceByValue.java b/java/src/Ice/src/main/java/com/zeroc/Ice/InterfaceByValue.java
index 86881bfe1a6..0d3593503f1 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/InterfaceByValue.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/InterfaceByValue.java
@@ -34,6 +34,7 @@ public class InterfaceByValue extends Value
         return _id;
     }
 
+    /** @hidden */
     @Override
     protected void _iceWriteImpl(OutputStream ostr)
     {
@@ -41,6 +42,7 @@ public class InterfaceByValue extends Value
         ostr.endSlice();
     }
 
+    /** @hidden */
     @Override
     protected void _iceReadImpl(InputStream istr)
     {
@@ -48,6 +50,7 @@ public class InterfaceByValue extends Value
         istr.endSlice();
     }
 
+    /** @hidden */
     public static final long serialVersionUID = 0L;
 
     private String _id;
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/MarshaledResult.java b/java/src/Ice/src/main/java/com/zeroc/Ice/MarshaledResult.java
index 129947f7a19..0cd63364a94 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/MarshaledResult.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/MarshaledResult.java
@@ -9,6 +9,7 @@
 
 package com.zeroc.Ice;
 
+/** @hidden */
 public interface MarshaledResult
 {
     OutputStream getOutputStream();
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/NativePropertiesAdmin.java b/java/src/Ice/src/main/java/com/zeroc/Ice/NativePropertiesAdmin.java
index eb962741e57..b08a8124b09 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/NativePropertiesAdmin.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/NativePropertiesAdmin.java
@@ -9,8 +9,22 @@
 
 package com.zeroc.Ice;
 
+/**
+ * Interface implemented by the Property admin facet. It allows users to add and remove
+ * callbacks that notify the application when Ice properties are updated at run time.
+ **/
 public interface NativePropertiesAdmin
 {
+    /**
+     * Adds a new update callback. The callback receives the updated properties each time
+     * the properties are updated.
+     * @param callback The new callback.
+     **/
     void addUpdateCallback(java.util.function.Consumer<java.util.Map<String, String>> callback);
+
+    /**
+     * Removes a previously registered update callback.
+     * @param callback The callback to remove.
+     **/
     void removeUpdateCallback(java.util.function.Consumer<java.util.Map<String, String>> callback);
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/Object.java b/java/src/Ice/src/main/java/com/zeroc/Ice/Object.java
index 9d7eb8b505f..b8355ee7936 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/Object.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/Object.java
@@ -18,6 +18,7 @@ import com.zeroc.IceInternal.Incoming;
  **/
 public interface Object
 {
+    /** @hidden */
     final static String[] _iceIds =
     {
         "::Ice::Object"
@@ -121,6 +122,7 @@ public interface Object
         return _iceIds[0];
     }
 
+    /** @hidden */
     final static String[] _iceOps =
     {
         "ice_id",
@@ -147,6 +149,13 @@ public interface Object
         return _iceDispatch(in, in.getCurrent());
     }
 
+    /**
+     * @hidden
+     * @param in -
+     * @param current -
+     * @return -
+     * @throws UserException -
+     **/
     default CompletionStage<OutputStream> _iceDispatch(Incoming in, Current current)
         throws UserException
     {
@@ -180,6 +189,10 @@ public interface Object
         throw new OperationNotExistException(current.id, current.facet, current.operation);
     }
 
+    /**
+     * @hidden
+     * @param ostr -
+     **/
     default void _iceWrite(OutputStream ostr)
     {
          ostr.startValue(null);
@@ -187,10 +200,18 @@ public interface Object
          ostr.endValue();
     }
 
+    /**
+     * @hidden
+     * @param ostr -
+     **/
     default void _iceWriteImpl(OutputStream ostr)
     {
     }
 
+    /**
+     * @hidden
+     * @param istr -
+     **/
     default void _iceRead(InputStream istr)
     {
          istr.startValue();
@@ -198,10 +219,21 @@ public interface Object
          istr.endValue(false);
     }
 
+    /**
+     * @hidden
+     * @param istr -
+     **/
     default void _iceReadImpl(InputStream istr)
     {
     }
 
+    /**
+     * @hidden
+     * @param obj -
+     * @param inS -
+     * @param current -
+     * @return -
+     **/
     static CompletionStage<OutputStream> _iceD_ice_isA(Object obj, Incoming inS, Current current)
     {
         InputStream istr = inS.startReadParams();
@@ -214,6 +246,13 @@ public interface Object
         return inS.setResult(ostr);
     }
 
+    /**
+     * @hidden
+     * @param obj -
+     * @param inS -
+     * @param current -
+     * @return -
+     **/
     static CompletionStage<OutputStream> _iceD_ice_ping(Object obj, Incoming inS, Current current)
     {
         inS.readEmptyParams();
@@ -221,6 +260,13 @@ public interface Object
         return inS.setResult(inS.writeEmptyParams());
     }
 
+    /**
+     * @hidden
+     * @param obj -
+     * @param inS -
+     * @param current -
+     * @return -
+     **/
     static CompletionStage<OutputStream> _iceD_ice_ids(Object obj, Incoming inS, Current current)
     {
         inS.readEmptyParams();
@@ -231,6 +277,13 @@ public interface Object
         return inS.setResult(ostr);
     }
 
+    /**
+     * @hidden
+     * @param obj -
+     * @param inS -
+     * @param current -
+     * @return -
+     **/
     static CompletionStage<OutputStream> _iceD_ice_id(Object obj, Incoming inS, Current current)
     {
         inS.readEmptyParams();
@@ -241,6 +294,11 @@ public interface Object
         return inS.setResult(ostr);
     }
 
+    /**
+     * @hidden
+     * @param mode -
+     * @return -
+     **/
     static String _iceOperationModeToString(OperationMode mode)
     {
         if(mode == OperationMode.Normal)
@@ -260,6 +318,11 @@ public interface Object
         return "???";
     }
 
+    /**
+     * @hidden
+     * @param expected -
+     * @param received -
+     **/
     static void _iceCheckMode(OperationMode expected, OperationMode received)
     {
         if(expected == null)
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java b/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java
index f6d3f92ede4..b7bcc9c25fb 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/ObjectPrx.java
@@ -711,6 +711,9 @@ public interface ObjectPrx
     @Override
     boolean equals(java.lang.Object r);
 
+    /**
+     * The type ID of the target's interface: "::Ice::Object".
+     **/
     static final String ice_staticId = "::Ice::Object";
 
     /**
@@ -849,28 +852,80 @@ public interface ObjectPrx
         return istr.readProxy();
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param id -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _checkedCast(ObjectPrx obj, String id, Class<T> proxy, Class<?> impl)
     {
         return _checkedCast(obj, false, null, noExplicitContext, id, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param ctx -
+     * @param id -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _checkedCast(ObjectPrx obj, java.util.Map<String, String> ctx, String id, Class<T> proxy,
                                Class<?> impl)
     {
         return _checkedCast(obj, false, null, ctx, id, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param facet -
+     * @param id -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _checkedCast(ObjectPrx obj, String facet, String id, Class<T> proxy, Class<?> impl)
     {
         return _checkedCast(obj, true, facet, noExplicitContext, id, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param facet -
+     * @param ctx -
+     * @param id -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _checkedCast(ObjectPrx obj, String facet, java.util.Map<String, String> ctx, String id,
                                Class<T> proxy, Class<?> impl)
     {
         return _checkedCast(obj, true, facet, ctx, id, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param explicitFacet -
+     * @param facet -
+     * @param ctx -
+     * @param id -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _checkedCast(ObjectPrx obj, boolean explicitFacet, String facet, java.util.Map<String, String> ctx,
                                String id, Class<T> proxy, Class<?> impl)
     {
@@ -925,16 +980,43 @@ public interface ObjectPrx
         return r;
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _uncheckedCast(ObjectPrx obj, Class<T> proxy, Class<?> impl)
     {
         return _uncheckedCast(obj, false, null, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param facet -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _uncheckedCast(ObjectPrx obj, String facet, Class<T> proxy, Class<?> impl)
     {
         return _uncheckedCast(obj, true, facet, proxy, impl);
     }
 
+    /**
+     * @hidden
+     * @param <T> -
+     * @param obj -
+     * @param explicitFacet -
+     * @param facet -
+     * @param proxy -
+     * @param impl -
+     * @return -
+     **/
     static <T> T _uncheckedCast(ObjectPrx obj, boolean explicitFacet, String facet, Class<T> proxy, Class<?> impl)
     {
         T r = null;
@@ -982,16 +1064,46 @@ public interface ObjectPrx
         return r;
     }
 
+    /**
+     * @hidden
+     * @param os -
+     **/
     void _write(OutputStream os);
+
+    /**
+     * @hidden
+     * @param p -
+     **/
     void _copyFrom(ObjectPrx p);
+
+    /**
+     * @hidden
+     * @return -
+     **/
     com.zeroc.IceInternal.Reference _getReference();
+
+    /**
+     * @hidden
+     * @param r -
+     * @return -
+     **/
     ObjectPrx _newInstance(com.zeroc.IceInternal.Reference r);
 
+    /**
+     * @hidden
+     * @param newContext -
+     * @return -
+     **/
     default ObjectPrx _ice_context(java.util.Map<String, String> newContext)
     {
         return _newInstance(_getReference().changeContext(newContext));
     }
 
+    /**
+     * @hidden
+     * @param newAdapterId -
+     * @return -
+     **/
     default ObjectPrx _ice_adapterId(String newAdapterId)
     {
         if(newAdapterId == null)
@@ -1009,6 +1121,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param newEndpoints -
+     * @return -
+     **/
     default ObjectPrx _ice_endpoints(Endpoint[] newEndpoints)
     {
         if(java.util.Arrays.equals(newEndpoints, _getReference().getEndpoints()))
@@ -1023,6 +1140,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param connection -
+     * @return -
+     **/
     default ObjectPrx _ice_fixed(com.zeroc.Ice.Connection connection)
     {
         if(connection == null)
@@ -1043,6 +1165,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param newTimeout -
+     * @return -
+     **/
     default ObjectPrx _ice_locatorCacheTimeout(int newTimeout)
     {
         if(newTimeout < -1)
@@ -1059,6 +1186,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param newTimeout -
+     * @return -
+     **/
     default ObjectPrx _ice_invocationTimeout(int newTimeout)
     {
         if(newTimeout < 1 && newTimeout != -1 && newTimeout != -2)
@@ -1075,6 +1207,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param newCache -
+     * @return -
+     **/
     default ObjectPrx _ice_connectionCached(boolean newCache)
     {
         if(newCache == _getReference().getCacheConnection())
@@ -1087,6 +1224,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param newType -
+     * @return -
+     **/
     default ObjectPrx _ice_endpointSelection(EndpointSelectionType newType)
     {
         if(newType == _getReference().getEndpointSelection())
@@ -1099,6 +1241,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param b -
+     * @return -
+     **/
     default ObjectPrx _ice_secure(boolean b)
     {
         if(b == _getReference().getSecure())
@@ -1111,6 +1258,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param e -
+     * @return -
+     **/
     default ObjectPrx _ice_encodingVersion(EncodingVersion e)
     {
         if(e.equals(_getReference().getEncoding()))
@@ -1123,6 +1275,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param b -
+     * @return -
+     **/
     default ObjectPrx _ice_preferSecure(boolean b)
     {
         if(b == _getReference().getPreferSecure())
@@ -1135,6 +1292,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param router -
+     * @return -
+     **/
     default ObjectPrx _ice_router(RouterPrx router)
     {
         com.zeroc.IceInternal.Reference ref = _getReference().changeRouter(router);
@@ -1148,6 +1310,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param locator -
+     * @return -
+     **/
     default ObjectPrx _ice_locator(LocatorPrx locator)
     {
         com.zeroc.IceInternal.Reference ref = _getReference().changeLocator(locator);
@@ -1161,6 +1328,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param b -
+     * @return -
+     **/
     default ObjectPrx _ice_collocationOptimized(boolean b)
     {
         if(b == _getReference().getCollocationOptimized())
@@ -1173,6 +1345,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     default ObjectPrx _ice_twoway()
     {
         if(_getReference().getMode() == com.zeroc.IceInternal.Reference.ModeTwoway)
@@ -1185,6 +1361,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     default ObjectPrx _ice_oneway()
     {
         if(_getReference().getMode() == com.zeroc.IceInternal.Reference.ModeOneway)
@@ -1197,6 +1377,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     default ObjectPrx _ice_batchOneway()
     {
         if(_getReference().getMode() == com.zeroc.IceInternal.Reference.ModeBatchOneway)
@@ -1209,6 +1393,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     default ObjectPrx _ice_datagram()
     {
         if(_getReference().getMode() == com.zeroc.IceInternal.Reference.ModeDatagram)
@@ -1221,6 +1409,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     default ObjectPrx _ice_batchDatagram()
     {
         if(_getReference().getMode() == com.zeroc.IceInternal.Reference.ModeBatchDatagram)
@@ -1233,6 +1425,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param co -
+     * @return -
+     **/
     default ObjectPrx _ice_compress(boolean co)
     {
         com.zeroc.IceInternal.Reference ref = _getReference().changeCompress(co);
@@ -1246,6 +1443,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param t -
+     * @return -
+     **/
     default ObjectPrx _ice_timeout(int t)
     {
         if(t < 1 && t != -1)
@@ -1263,6 +1465,11 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * @hidden
+     * @param connectionId -
+     * @return -
+     **/
     default ObjectPrx _ice_connectionId(String connectionId)
     {
         com.zeroc.IceInternal.Reference ref = _getReference().changeConnectionId(connectionId);
@@ -1276,5 +1483,10 @@ public interface ObjectPrx
         }
     }
 
+    /**
+     * A special empty context that is indistinguishable from the absence of a context parameter.
+     * For example, <code>prx.op(noExplicitContext)</code> is the same as <code>prx.op()</code>
+     * and does not override the current implicit context (if any).
+     **/
     static final java.util.Map<String, String> noExplicitContext = new java.util.HashMap<>();
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java b/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
index 76afa687cec..c7ad9ea20b7 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/OutputStream.java
@@ -9,6 +9,12 @@
 
 package com.zeroc.Ice;
 
+/**
+ * Interface to marshal (write) Slice types into sequence of bytes encoded using the
+ * Ice encoding.
+ *
+ * @see InputStream
+ **/
 public class OutputStream
 {
     /**
@@ -2458,6 +2464,7 @@ public class OutputStream
         }
     }
 
+    /** @hidden */
     @FunctionalInterface
     static public interface Marshaler
     {
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/UnknownSlicedValue.java b/java/src/Ice/src/main/java/com/zeroc/Ice/UnknownSlicedValue.java
index cbe20e8fd44..6198cdc7226 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/UnknownSlicedValue.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/UnknownSlicedValue.java
@@ -47,6 +47,7 @@ public final class UnknownSlicedValue extends Value
         return _unknownTypeId;
     }
 
+    /** @hidden */
     @Override
     public void _iceWrite(OutputStream ostr)
     {
@@ -54,6 +55,7 @@ public final class UnknownSlicedValue extends Value
         ostr.endValue();
     }
 
+    /** @hidden */
     @Override
     public void _iceRead(InputStream istr)
     {
@@ -64,5 +66,6 @@ public final class UnknownSlicedValue extends Value
     private final String _unknownTypeId;
     private SlicedData _slicedData;
 
+    /** @hidden */
     public static final long serialVersionUID = 0L;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/UserException.java b/java/src/Ice/src/main/java/com/zeroc/Ice/UserException.java
index 845b7156344..002d687951c 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/UserException.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/UserException.java
@@ -94,6 +94,10 @@ public abstract class UserException extends java.lang.Exception implements Clone
         return sw.toString();
     }
 
+    /**
+     * @hidden
+     * @param os -
+     **/
     public void _write(OutputStream os)
     {
         os.startException(null);
@@ -101,6 +105,10 @@ public abstract class UserException extends java.lang.Exception implements Clone
         os.endException();
     }
 
+    /**
+     * @hidden
+     * @param is -
+     **/
     public void _read(InputStream is)
     {
         is.startException();
@@ -108,14 +116,27 @@ public abstract class UserException extends java.lang.Exception implements Clone
         is.endException(false);
     }
 
+    /**
+     * @hidden
+     * @return -
+     **/
     public boolean _usesClasses()
     {
         return false;
     }
 
+    /**
+     * @hidden
+     * @param os -
+     **/
     protected abstract void _writeImpl(OutputStream os);
 
+    /**
+     * @hidden
+     * @param is -
+     **/
     protected abstract void _readImpl(InputStream is);
 
+     /** @hidden */
     public static final long serialVersionUID = 0L;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/Value.java b/java/src/Ice/src/main/java/com/zeroc/Ice/Value.java
index a2a86d817a0..0ac9a321708 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/Value.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/Value.java
@@ -78,6 +78,10 @@ public abstract class Value implements java.lang.Cloneable, java.io.Serializable
         return "::Ice::Object";
     }
 
+    /**
+     * @hidden
+     * @param ostr -
+     **/
     public void _iceWrite(OutputStream ostr)
     {
         ostr.startValue(null);
@@ -85,6 +89,10 @@ public abstract class Value implements java.lang.Cloneable, java.io.Serializable
         ostr.endValue();
     }
 
+    /**
+     * @hidden
+     * @param istr -
+     **/
     public void _iceRead(InputStream istr)
     {
         istr.startValue();
@@ -92,13 +100,22 @@ public abstract class Value implements java.lang.Cloneable, java.io.Serializable
         istr.endValue(false);
     }
 
+    /**
+     * @hidden
+     * @param ostr -
+     **/
     protected void _iceWriteImpl(OutputStream ostr)
     {
     }
 
+    /**
+     * @hidden
+     * @param istr -
+     **/
     protected void _iceReadImpl(InputStream istr)
     {
     }
 
+    /** @hidden */
     public static final long serialVersionUID = 0L;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/ValueReader.java b/java/src/Ice/src/main/java/com/zeroc/Ice/ValueReader.java
index c23d94e9c1a..31a25f81cc9 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/ValueReader.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/ValueReader.java
@@ -21,17 +21,20 @@ public abstract class ValueReader extends Value
      **/
     public abstract void read(InputStream in);
 
+    /** @hidden */
     @Override
     public void _iceWrite(OutputStream os)
     {
         assert(false);
     }
 
+    /** @hidden */
     @Override
     public void _iceRead(InputStream is)
     {
         read(is);
     }
 
+    /** @hidden */
     public static final long serialVersionUID = 0L;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/ValueWriter.java b/java/src/Ice/src/main/java/com/zeroc/Ice/ValueWriter.java
index aff9f2d34a7..ca48470a730 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/ValueWriter.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/ValueWriter.java
@@ -21,17 +21,20 @@ public abstract class ValueWriter extends Value
      **/
     public abstract void write(OutputStream out);
 
+    /** @hidden */
     @Override
     public void _iceWrite(OutputStream os)
     {
         write(os);
     }
 
+    /** @hidden */
     @Override
     public void _iceRead(InputStream is)
     {
         assert(false);
     }
 
+    /** @hidden */
     public static final long serialVersionUID = 0L;
 }
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/_ObjectPrxFactoryMethods.java b/java/src/Ice/src/main/java/com/zeroc/Ice/_ObjectPrxFactoryMethods.java
index b99c812bfba..b9fc8743854 100644
--- a/java/src/Ice/src/main/java/com/zeroc/Ice/_ObjectPrxFactoryMethods.java
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/_ObjectPrxFactoryMethods.java
@@ -10,6 +10,7 @@
 package com.zeroc.Ice;
 
 /**
+ * @hidden
  * Provides overloads of the proxy factory methods with covariant return types
  * so that applications do not need to downcast to the derived proxy type.
  **/
diff --git a/java/src/Ice/src/main/java/com/zeroc/Ice/package-info.java b/java/src/Ice/src/main/java/com/zeroc/Ice/package-info.java
new file mode 100644
index 00000000000..c66c5b6a4f1
--- /dev/null
+++ b/java/src/Ice/src/main/java/com/zeroc/Ice/package-info.java
@@ -0,0 +1,13 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * Core APIs of the Ice framework.
+ **/
+package com.zeroc.Ice;
diff --git a/java/src/Ice/src/main/java/com/zeroc/IceMX/package-info.java b/java/src/Ice/src/main/java/com/zeroc/IceMX/package-info.java
new file mode 100644
index 00000000000..8940e8c62ca
--- /dev/null
+++ b/java/src/Ice/src/main/java/com/zeroc/IceMX/package-info.java
@@ -0,0 +1,13 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * Ice Management Extension (IceMX) APIs.
+ **/
+package com.zeroc.IceMX;
diff --git a/java/src/IceBT/build.gradle b/java/src/IceBT/build.gradle
index bd1ef55fe93..dadbfd4d558 100644
--- a/java/src/IceBT/build.gradle
+++ b/java/src/IceBT/build.gradle
@@ -15,9 +15,7 @@ project.ext.description = "Bluetooth support for Ice"
 
 slice {
     java {
-        set1 {
-            files = fileTree(dir: "$project.ext.topSrcDir/slice/IceBT", includes:['*.ice'], excludes:["*F.ice"])
-        }
+        files = fileTree(dir: "$project.ext.topSrcDir/slice/IceBT", includes:['*.ice'], excludes:["*F.ice"])
     }
 }
 
@@ -34,3 +32,7 @@ jar {
     //
     exclude("android/**")
 }
+
+javadoc {
+    excludes = ["**/android/*", "**/*I.java", "**/Instance.java"]
+}
diff --git a/java/src/IceBT/src/main/java/com/zeroc/IceBT/PluginFactory.java b/java/src/IceBT/src/main/java/com/zeroc/IceBT/PluginFactory.java
index 07a35d95392..d07e468e63f 100644
--- a/java/src/IceBT/src/main/java/com/zeroc/IceBT/PluginFactory.java
+++ b/java/src/IceBT/src/main/java/com/zeroc/IceBT/PluginFactory.java
@@ -10,12 +10,12 @@
 package com.zeroc.IceBT;
 
 /**
- * Plug-in factories must implement this interface.
+ * Creates IceBT plug-ins.
  **/
 public class PluginFactory implements com.zeroc.Ice.PluginFactory
 {
     /**
-     * Returns a new plug-in.
+     * Returns a new IceBT plug-in.
      *
      * @param communicator The communicator for the plug-in.
      * @param name The name of the plug-in.
diff --git a/java/src/IceBT/src/main/java/com/zeroc/IceBT/package-info.java b/java/src/IceBT/src/main/java/com/zeroc/IceBT/package-info.java
new file mode 100644
index 00000000000..5e28e002c0f
--- /dev/null
+++ b/java/src/IceBT/src/main/java/com/zeroc/IceBT/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for the IceBT plug-in, a Bluetooth transport currently available
+ * only for Android.
+ **/
+package com.zeroc.IceBT;
diff --git a/java/src/IceBox/build.gradle b/java/src/IceBox/build.gradle
index 0180721da92..14622d456d3 100644
--- a/java/src/IceBox/build.gradle
+++ b/java/src/IceBox/build.gradle
@@ -27,3 +27,7 @@ dependencies {
 }
 
 apply from: "$project.ext.topSrcDir/java/gradle/library.gradle"
+
+javadoc {
+    excludes = ["**/Admin.java", "**/Server.java", "**/ServiceManagerI.java"]
+}
diff --git a/java/src/IceBox/src/main/java/com/zeroc/IceBox/package-info.java b/java/src/IceBox/src/main/java/com/zeroc/IceBox/package-info.java
new file mode 100644
index 00000000000..b1fbebdff08
--- /dev/null
+++ b/java/src/IceBox/src/main/java/com/zeroc/IceBox/package-info.java
@@ -0,0 +1,13 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for creating IceBox services and interacting with the IceBox server.
+ **/
+package com.zeroc.IceBox;
diff --git a/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginFactory.java b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginFactory.java
index 72d72d864d1..164e383bc64 100644
--- a/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginFactory.java
+++ b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginFactory.java
@@ -9,6 +9,9 @@
 
 package com.zeroc.IceDiscovery;
 
+/**
+ * Creates IceDiscovery plug-ins.
+ **/
 public class PluginFactory implements com.zeroc.Ice.PluginFactory
 {
     @Override
diff --git a/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginI.java b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginI.java
index 482dfc2df8a..09f3b4d5429 100644
--- a/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginI.java
+++ b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/PluginI.java
@@ -11,7 +11,7 @@ package com.zeroc.IceDiscovery;
 
 import com.zeroc.IceInternal.Network;
 
-public class PluginI implements com.zeroc.Ice.Plugin
+class PluginI implements com.zeroc.Ice.Plugin
 {
     public PluginI(com.zeroc.Ice.Communicator communicator)
     {
diff --git a/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/package-info.java b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/package-info.java
new file mode 100644
index 00000000000..a4c59723c1f
--- /dev/null
+++ b/java/src/IceDiscovery/src/main/java/com/zeroc/IceDiscovery/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for the IceDiscovery plug-in. IceDiscovery lets client applications
+ * discover servers using UDP multicast.
+ **/
+package com.zeroc.IceDiscovery;
diff --git a/java/src/IceGrid/src/main/java/com/zeroc/IceGrid/package-info.java b/java/src/IceGrid/src/main/java/com/zeroc/IceGrid/package-info.java
new file mode 100644
index 00000000000..ea28cfc2bf5
--- /dev/null
+++ b/java/src/IceGrid/src/main/java/com/zeroc/IceGrid/package-info.java
@@ -0,0 +1,13 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for clients of the IceGrid location service.
+ **/
+package com.zeroc.IceGrid;
diff --git a/java/src/IceGridGUI/build.gradle b/java/src/IceGridGUI/build.gradle
index bd422772640..983be322e62 100644
--- a/java/src/IceGridGUI/build.gradle
+++ b/java/src/IceGridGUI/build.gradle
@@ -32,6 +32,9 @@ if(!project.ext.hasJavaFx) {
     }
 }
 
+// Don't generate javadoc
+javadoc.enabled = false
+
 // Disable deprecation warnings caused by JGoodies
 tasks.withType(JavaCompile) {
     options.deprecation = false
@@ -73,7 +76,6 @@ if(icegridguiProguard.toBoolean()) {
 }
 apply from: jarBuilder
 
-
 clean {
     delete("${libDir}/${jarName}")
     delete("${libDir}/IceGrid GUI.app")
diff --git a/java/src/IceLocatorDiscovery/src/main/java/com/zeroc/IceLocatorDiscovery/package-info.java b/java/src/IceLocatorDiscovery/src/main/java/com/zeroc/IceLocatorDiscovery/package-info.java
new file mode 100644
index 00000000000..d0a49b91301
--- /dev/null
+++ b/java/src/IceLocatorDiscovery/src/main/java/com/zeroc/IceLocatorDiscovery/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for the IceLocatorDiscovery plug-in. IceLocatorDiscovery discovers Ice
+ * locators (such as IceGrid registries) using UDP multicast.
+ **/
+package com.zeroc.IceLocatorDiscovery;
diff --git a/java/src/IcePatch2/src/main/java/com/zeroc/IcePatch2/package-info.java b/java/src/IcePatch2/src/main/java/com/zeroc/IcePatch2/package-info.java
new file mode 100644
index 00000000000..2971824bf09
--- /dev/null
+++ b/java/src/IcePatch2/src/main/java/com/zeroc/IcePatch2/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for clients of the IcePatch2 file patching service.
+ * @deprecated
+ **/
+package com.zeroc.IcePatch2;
diff --git a/java/src/IceSSL/src/main/java/com/zeroc/IceSSL/package-info.java b/java/src/IceSSL/src/main/java/com/zeroc/IceSSL/package-info.java
new file mode 100644
index 00000000000..73375b422e6
--- /dev/null
+++ b/java/src/IceSSL/src/main/java/com/zeroc/IceSSL/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * APIs for the IceSSL transport plug-in. IceSSL provides encryption using
+ * SSL/TLS.
+ **/
+package com.zeroc.IceSSL;
diff --git a/java/src/IceStorm/src/main/java/com/zeroc/IceStorm/package-info.java b/java/src/IceStorm/src/main/java/com/zeroc/IceStorm/package-info.java
new file mode 100644
index 00000000000..3dc5772b3d1
--- /dev/null
+++ b/java/src/IceStorm/src/main/java/com/zeroc/IceStorm/package-info.java
@@ -0,0 +1,14 @@
+// **********************************************************************
+//
+// Copyright (c) 2003-2018 ZeroC, Inc. All rights reserved.
+//
+// This copy of Ice is licensed to you under the terms described in the
+// ICE_LICENSE file included in this distribution.
+//
+// **********************************************************************
+
+/**
+ * IceStorm APIs. IceStorm is a broker-based pub/sub service, where
+ * subscribers connect to publishers using topics.
+ **/
+package com.zeroc.IceStorm;
diff --git a/java/test/build.gradle b/java/test/build.gradle
index 0c3cbccd404..4c18dda764e 100644
--- a/java/test/build.gradle
+++ b/java/test/build.gradle
@@ -10,6 +10,9 @@
 ext.testDir = "${projectDir}/src/main/java/test"
 apply from: "slice.gradle"
 
+// Don't generate javadoc
+javadoc.enabled = false
+
 sourceSets {
     main {
         java {
diff --git a/java/test/plugins/build.gradle b/java/test/plugins/build.gradle
index 7971218f6da..e480536647c 100644
--- a/java/test/plugins/build.gradle
+++ b/java/test/plugins/build.gradle
@@ -10,6 +10,9 @@
 sourceCompatibility = iceSourceCompatibility
 targetCompatibility = iceTargetCompatibility
 
+// Don't generate javadoc
+javadoc.enabled = false
+
 sourceSets {
     main {
         java {