ICE-6864 - Java changes for Slice docs

2 files changed, 183 insertions, 68 deletions

diff --git a/cpp/src/slice2java/Gen.cpp b/cpp/src/slice2java/Gen.cpp
index 608a492c31f..8050a34577a 100644
--- a/cpp/src/slice2java/Gen.cpp
+++ b/cpp/src/slice2java/Gen.cpp
@@ -435,7 +435,7 @@ Slice::JavaVisitor::getAsyncCallbackBaseClass(const OperationPtr& op, bool funct
 }
 
 string
-Slice::JavaVisitor::getLambdaResposeCB(const OperationPtr& op, const string& package)
+Slice::JavaVisitor::getLambdaResponseCB(const OperationPtr& op, const string& package)
 {
     TypePtr ret = op->returnType();
     ParamDeclList outParams = getOutParams(op);
@@ -505,7 +505,7 @@ Slice::JavaVisitor::getParamsAsyncLambda(const OperationPtr& op, const string& p
         params.push_back("java.util.Map<String, String> __ctx");
     }
 
-    params.push_back(getLambdaResposeCB(op, package) + " __responseCb");
+    params.push_back(getLambdaResponseCB(op, package) + " __responseCb");
 
     if(!op->throws().empty())
     {
@@ -2068,7 +2068,8 @@ Slice::JavaVisitor::writeDocComment(Output& out, const ContainedPtr& p, const st
             doneExtraParam = true;
         }
         out << nl << " *";
-        if(!(*i).empty()) {
+        if(!(*i).empty())
+        {
             out << " " << *i;
         }
     }
@@ -2091,6 +2092,30 @@ Slice::JavaVisitor::writeDocComment(Output& out, const ContainedPtr& p, const st
 }
 
 void
+Slice::JavaVisitor::writeDocComment(Output& out, const string& deprecateReason, const string& summary)
+{
+    vector<string> lines;
+    IceUtilInternal::splitString(summary, "\n", lines);
+
+    out << nl << "/**";
+    for(vector<string>::const_iterator i = lines.begin(); i != lines.end(); ++i)
+    {
+        out << nl << " *";
+        if(!(*i).empty())
+        {
+            out << " " << *i;
+        }
+    }
+
+    if(!deprecateReason.empty())
+    {
+        out << nl << " * @deprecated " << deprecateReason;
+    }
+
+    out << nl << " **/";
+}
+
+void
 Slice::JavaVisitor::writeDocCommentOp(Output& out, const OperationPtr& p)
 {
     ContainerPtr container = p->container();
@@ -2223,7 +2248,8 @@ Slice::JavaVisitor::writeDocCommentAsync(Output& out, const OperationPtr& p, Par
 
 void
 Slice::JavaVisitor::writeDocCommentAMI(Output& out, const OperationPtr& p, ParamDir paramType,
-                                       const string& extraParam1, const string& extraParam2, const string& extraParam3)
+                                       const string& extraParam1, const string& extraParam2, const string& extraParam3,
+                                       const string& extraParam4, const string& extraParam5)
 {
     ContainerPtr container = p->container();
     ClassDefPtr contained = ClassDefPtr::dynamicCast(container);
@@ -2273,6 +2299,16 @@ Slice::JavaVisitor::writeDocCommentAMI(Output& out, const OperationPtr& p, Param
         out << nl << " * " << extraParam3;
     }
 
+    if(!extraParam4.empty())
+    {
+        out << nl << " * " << extraParam4;
+    }
+
+    if(!extraParam5.empty())
+    {
+        out << nl << " * " << extraParam5;
+    }
+
     if(paramType == InParam)
     {
         out << nl << " * @return The asynchronous result object.";
@@ -4860,7 +4896,8 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
     // by applications (e.g., checkedCast, etc.)
     //
     out << sp;
-    writeDocComment(out, p, getDeprecateReason(p, 0, p->isInterface() ? "interface" : "class"));
+    writeDocComment(out, getDeprecateReason(p, 0, p->isInterface() ? "interface" : "class"),
+                    "Provides type-specific helper functions.");
     out << nl << "public final class " << name << "PrxHelper extends Ice.ObjectPrxHelperBase implements " << name
         << "Prx";
 
@@ -4905,7 +4942,6 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         const string retS = typeToString(ret, TypeModeReturn, package, op->getMetaData(), true, op->returnIsOptional());
 
         out << sp;
-        writeDocCommentAsync(out, op, OutParam);
         out << nl << "public " << retS << " end_" << op->name() << spar << outParams << "Ice.AsyncResult __iresult"
             << epar;
         writeThrowsClause(package, throws);
@@ -5087,38 +5123,77 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         }
     }
 
-    out << sp << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj)";
+    out << sp;
+    writeDocComment(out, "",
+                    "Contacts the remote server to verify that the object implements this type.\n"
+                    "Raises a local exception if a communication error occurs.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@return A proxy for this type, or null if the object does not support this type.");
+    out << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj)";
     out << sb;
     out << nl << "return checkedCastImpl(__obj, ice_staticId(), " << name << "Prx.class, "
         << name << "PrxHelper.class);";
     out << eb;
 
-    out << sp << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, " << contextParam << ')';
+    out << sp;
+    writeDocComment(out, "",
+                    "Contacts the remote server to verify that the object implements this type.\n"
+                    "Raises a local exception if a communication error occurs.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@param __ctx The Context map to send with the invocation.\n"
+                    "@return A proxy for this type, or null if the object does not support this type.");
+    out << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, " << contextParam << ')';
     out << sb;
     out << nl << "return checkedCastImpl(__obj, __ctx, ice_staticId(), " << name
         << "Prx.class, " << name << "PrxHelper.class);";
     out << eb;
 
-    out << sp << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, String __facet)";
+    out << sp;
+    writeDocComment(out, "",
+                    "Contacts the remote server to verify that a facet of the object implements this type.\n"
+                    "Raises a local exception if a communication error occurs.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@param __facet The name of the desired facet.\n"
+                    "@return A proxy for this type, or null if the object does not support this type.");
+    out << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, String __facet)";
     out << sb;
     out << nl << "return checkedCastImpl(__obj, __facet, ice_staticId(), " << name
         << "Prx.class, " << name << "PrxHelper.class);";
     out << eb;
 
-    out << sp << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, String __facet, "
+    out << sp;
+    writeDocComment(out, "",
+                    "Contacts the remote server to verify that a facet of the object implements this type.\n"
+                    "Raises a local exception if a communication error occurs.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@param __facet The name of the desired facet.\n"
+                    "@param __ctx The Context map to send with the invocation.\n"
+                    "@return A proxy for this type, or null if the object does not support this type.");
+    out << nl << "public static " << name << "Prx checkedCast(Ice.ObjectPrx __obj, String __facet, "
         << contextParam << ')';
     out << sb;
     out << nl << "return checkedCastImpl(__obj, __facet, __ctx, ice_staticId(), " << name
         << "Prx.class, " << name << "PrxHelper.class);";
     out << eb;
 
-    out << sp << nl << "public static " << name << "Prx uncheckedCast(Ice.ObjectPrx __obj)";
+    out << sp;
+    writeDocComment(out, "",
+                    "Downcasts the given proxy to this type without contacting the remote server.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@return A proxy for this type.");
+    out << nl << "public static " << name << "Prx uncheckedCast(Ice.ObjectPrx __obj)";
     out << sb;
     out << nl << "return uncheckedCastImpl(__obj, " << name << "Prx.class, " << name
         << "PrxHelper.class);";
     out << eb;
 
-    out << sp << nl << "public static " << name << "Prx uncheckedCast(Ice.ObjectPrx __obj, String __facet)";
+    out << sp;
+    writeDocComment(out, "",
+                    "Downcasts the given proxy to this type without contacting the remote server.\n"
+                    "@param __obj The untyped proxy.\n"
+                    "@param __facet The name of the desired facet.\n"
+                    "@return A proxy for this type.");
+    out << nl << "public static " << name << "Prx uncheckedCast(Ice.ObjectPrx __obj, String __facet)";
     out << sb;
     out << nl << "return uncheckedCastImpl(__obj, __facet, " << name << "Prx.class, " << name
         << "PrxHelper.class);";
@@ -5152,7 +5227,11 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
 
     out << eb << ';';
 
-    out << sp << nl << "public static String ice_staticId()";
+    out << sp;
+    writeDocComment(out, "",
+                    "Provides the Slice type ID of this type.\n"
+                    "@return The Slice type ID.");
+    out << nl << "public static String ice_staticId()";
     out << sb;
     out << nl << "return __ids[" << scopedPos << "];";
     out << eb;
@@ -5176,12 +5255,22 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
 
     if(_stream)
     {
-        out << sp << nl << "public static void write(Ice.OutputStream __outS, " << name << "Prx v)";
+        out << sp;
+        writeDocComment(out, "",
+                        "Writes the proxy to the stream.\n"
+                        "@param __outS The output stream.\n"
+                        "@param v The proxy to write. A null value is legal.");
+        out << nl << "public static void write(Ice.OutputStream __outS, " << name << "Prx v)";
         out << sb;
         out << nl << "__outS.writeProxy(v);";
         out << eb;
 
-        out << sp << nl << "public static " << name << "Prx read(Ice.InputStream __inS)";
+        out << sp;
+        writeDocComment(out, "",
+                        "Reads a proxy from the stream.\n"
+                        "@param __inS The input stream.\n"
+                        "@return The proxy, which may be null.");
+        out << nl << "public static " << name << "Prx read(Ice.InputStream __inS)";
         out << sb;
         out << nl << "Ice.ObjectPrx proxy = __inS.readProxy();";
         out << nl << "if(proxy != null)";
@@ -5193,7 +5282,11 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         out << nl << "return null;";
         out << eb;
 
-        out << sp << nl << "public static Ice.OptionalFormat optionalFormat()";
+        out << sp;
+        writeDocComment(out, "",
+                        "Provides the optional format for a proxy of this type.\n"
+                        "@return The optional format.");
+        out << nl << "public static Ice.OptionalFormat optionalFormat()";
         out << sb;
         out << nl << "return Ice.OptionalFormat.FSize;";
         out << eb;
@@ -5216,20 +5309,37 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
 
         Output& out2 = output();
 
-        out2 << sp << nl << "public final class " << name << "Helper";
+        out << sp;
+        writeDocComment(out, getDeprecateReason(p, 0, p->isInterface() ? "interface" : "class"),
+                        "Provides type-specific helper functions.");
+        out2 << nl << "public final class " << name << "Helper";
         out2 << sb;
 
-        out2 << sp << nl << "public static void write(Ice.OutputStream __outS, " << fixKwd(name) << " __v)";
+        out << sp;
+        writeDocComment(out, "",
+                        "Writes an instance to the stream.\n"
+                        "@param __outS The output stream.\n"
+                        "@param __v The instance to write. A null value is legal.");
+        out2 << nl << "public static void write(Ice.OutputStream __outS, " << fixKwd(name) << " __v)";
         out2 << sb;
         out2 << nl << "__outS.writeObject(__v);";
         out2 << eb;
 
-        out2 << sp << nl << "public static void read(Ice.InputStream __inS, " << name << "Holder __h)";
+        out << sp;
+        writeDocComment(out, "",
+                        "Reads an instance from the stream.\n"
+                        "@param __inS The input stream.\n"
+                        "@param __h A holder to contain the instance when it is eventually unmarshaled.");
+        out2 << nl << "public static void read(Ice.InputStream __inS, " << name << "Holder __h)";
         out2 << sb;
         out2 << nl << "__inS.readObject(__h);";
         out2 << eb;
 
-        out2 << sp << nl << "public static Ice.OptionalFormat optionalFormat()";
+        out << sp;
+        writeDocComment(out, "",
+                        "Provides the optional format for an instance of this type.\n"
+                        "@return The optional format.");
+        out2 << nl << "public static Ice.OptionalFormat optionalFormat()";
         out2 << sb;
         out2 << nl << "return " << getOptionalFormat(p->declaration()) << ';';
         out2 << eb;
@@ -5564,16 +5674,11 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
     throws.sort();
     throws.unique();
 
-    const string deprecateReason = getDeprecateReason(op, cl, "operation");
-    const string contextDoc = "@param __ctx The Context map to send with the invocation.";
-
     //
     // Write two synchronous versions of the operation - with and without a
     // context parameter.
     //
-    out << sp;
-    writeDocComment(out, op, deprecateReason);
-    out << nl << "public " << retS << ' ' << opName << spar << params << epar;
+    out << sp << nl << "public " << retS << ' ' << opName << spar << params << epar;
     writeThrowsClause(package, throws);
     out << sb;
     out << nl;
@@ -5584,9 +5689,7 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
     out << opName << spar << args << "null" << "false" << epar << ';';
     out << eb;
 
-    out << sp;
-    writeDocComment(out, op, deprecateReason, contextDoc);
-    out << nl << "public " << retS << ' ' << opName << spar << params << contextParam << epar;
+    out << sp << nl << "public " << retS << ' ' << opName << spar << params << contextParam << epar;
     writeThrowsClause(package, throws);
     out << sb;
     out << nl;
@@ -5649,33 +5752,29 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
         //
         // Type-unsafe begin methods
         //
-        out << sp;
-        writeDocCommentAsync(out, op, InParam);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << epar;
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "null" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "null" << epar
+            << ';';
         out << eb;
 
-        out << sp;
-        writeDocCommentAsync(out, op, InParam, contextDoc);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam << epar;
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "null" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "null" << epar
+            << ';';
         out << eb;
 
-        out << sp;
-        writeDocCommentAsync(out, op, InParam);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << callbackParam << epar;
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << callbackParam << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "__cb" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "__cb" << epar
+            << ';';
         out << eb;
 
-        out << sp;
-        writeDocCommentAsync(out, op, InParam, contextDoc);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam
             << callbackParam << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "__cb" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "__cb" << epar
+            << ';';
         out << eb;
 
         //
@@ -5692,20 +5791,18 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
         string opClassName = getAbsolute(cl, package, "Callback_", '_' + op->name());
         typeSafeCallbackParam = opClassName + " __cb";
 
-        out << sp;
-        writeDocCommentAsync(out, op, InParam);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << typeSafeCallbackParam
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << typeSafeCallbackParam
             << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "__cb" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "null" << "false" << "false" << "__cb" << epar
+            << ';';
         out << eb;
 
-        out << sp;
-        writeDocCommentAsync(out, op, InParam, contextDoc);
-        out << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam
+        out << sp << nl << "public Ice.AsyncResult begin_" << op->name() << spar << inParams << contextParam
             << typeSafeCallbackParam << epar;
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "__cb" << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << inArgs << "__ctx" << "true" << "false" << "__cb" << epar
+            << ';';
         out << eb;
 
         //
@@ -5737,7 +5834,8 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
         out << nl << "public Ice.AsyncResult begin_" << op->name();
         writeParamList(out, getParamsAsyncLambda(op, package, true, true, optionalMapping));
         out << sb;
-        out << nl << "return begin_" << op->name() << spar << getArgsAsyncLambda(op, package, true, true) << epar << ';';
+        out << nl << "return begin_" << op->name() << spar << getArgsAsyncLambda(op, package, true, true) << epar
+            << ';';
         out << eb;
 
         vector<string> params = inParams;
@@ -5768,7 +5866,7 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
         else if((ret && !outParams.empty()) || (outParams.size() > 1))
         {
             params.clear();
-            params.push_back(getLambdaResposeCB(op, package) + " responseCb");
+            params.push_back(getLambdaResponseCB(op, package) + " responseCb");
             if(!throws.empty())
             {
                 params.push_back("IceInternal.Functional_GenericCallback1<Ice.UserException> userExceptionCb");
@@ -5811,10 +5909,9 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
             out << nl << p->name() << "PrxHelper.__" << op->name() << "_completed(this, __result);";
             out << eb;
             out << sp;
-            out << nl << "private final " << getLambdaResposeCB(op, package) << " __responseCb;";
+            out << nl << "private final " << getLambdaResponseCB(op, package) << " __responseCb;";
             out << eb;
 
-
             out << nl << "return begin_" << op->name() << spar << getInOutArgs(op, InParam) << "__ctx"
                 << "__explicitCtx"
                 << "__synchronous"
@@ -5832,8 +5929,9 @@ Slice::Gen::HelperVisitor::writeOperation(const ClassDefPtr& p, const string& pa
             const string baseClass = getAsyncCallbackBaseClass(op, true);
             out << nl << "return begin_" << op->name();
             writeParamList(out, params, false, false);
-            out << nl << (throws.empty() ? "new " + baseClass + "(__responseCb, __exceptionCb, __sentCb)" :
-                                           "new " + baseClass + "(__responseCb, __userExceptionCb, __exceptionCb, __sentCb)");
+            out << nl
+                << (throws.empty() ? "new " + baseClass + "(__responseCb, __exceptionCb, __sentCb)" :
+                                     "new " + baseClass + "(__responseCb, __userExceptionCb, __exceptionCb, __sentCb)");
             out.inc();
             out << sb;
             out << nl << "public final void __completed(Ice.AsyncResult __result)";
@@ -5987,12 +6085,15 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     string deprecateReason = getDeprecateReason(p, cl, "operation");
     string contextDoc = "@param __ctx The Context map to send with the invocation.";
     string contextParam = "java.util.Map<String, String> __ctx";
+    string lambdaResponseDoc = "@param __responseCb The lambda response callback.";
+    string lambdaUserExDoc = "@param __userExceptionCb The lambda user exception callback.";
+    string lambdaExDoc = "@param __exceptionCb The lambda exception callback.";
+    string lambdaSentDoc = "@param __sentCb The lambda sent callback.";
 
     const bool optional = p->sendsOptionals();
 
     //
-    // Write two synchronous versions of the operation - with and without a
-    // context parameter.
+    // Write two synchronous versions of the operation - with and without a context parameter.
     //
     out << sp;
     writeDocComment(out, p, deprecateReason);
@@ -6017,14 +6118,12 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
         out << sp;
         writeDocComment(out, p, deprecateReason);
-
         out << nl << "public " << retS << ' ' << name << spar << reqParams << epar;
         writeThrowsClause(package, throws);
         out << ';';
 
         out << sp;
         writeDocComment(out, p, deprecateReason, contextDoc);
-
         out << nl << "public " << retS << ' ' << name << spar << reqParams << contextParam << epar;
         writeThrowsClause(package, throws);
         out << ';';
@@ -6082,9 +6181,9 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
             << typeSafeCallbackParam << epar << ';';
 
         //
-        // Generate the Callback Response interface if the operation has more that one
+        // Generate the Callback Response interface if the operation has more than one
         // return parameter. Operations with just one return parameter use one of the
-        // builtin async callbacks interfaces.
+        // builtin async callback interfaces.
         //
         {
             ParamDeclList outParams = getOutParams(p);
@@ -6092,7 +6191,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
             {
                 vector<string> params = getParamsAsyncCB(p, package, false, true);
                 out << sp;
-                out << nl << "public interface " << getLambdaResposeCB(p, package);
+                out << nl << "public interface " << getLambdaResponseCB(p, package);
                 out << sb;
                 out << nl << "void apply" << spar << params << epar << ';';
                 out << eb;
@@ -6104,21 +6203,28 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         //
         {
             out << sp;
+            writeDocCommentAMI(out, p, InParam, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc, lambdaExDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, false, false, true));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc, lambdaExDoc,
+                               lambdaSentDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, false, true, true));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, contextDoc, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc,
+                               lambdaExDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, true, false, true));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, contextDoc, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc,
+                               lambdaExDoc, lambdaSentDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, true, true, true));
             out << ';';
@@ -6165,21 +6271,28 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         //
         {
             out << sp;
+            writeDocCommentAMI(out, p, InParam, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc, lambdaExDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc, lambdaExDoc,
+                               lambdaSentDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, false, true));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, contextDoc, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc,
+                               lambdaExDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, true));
             out << ';';
 
             out << sp;
+            writeDocCommentAMI(out, p, InParam, contextDoc, lambdaResponseDoc, throws.empty() ? "" : lambdaUserExDoc,
+                               lambdaExDoc, lambdaSentDoc);
             out << nl << "public Ice.AsyncResult begin_" << p->name();
             writeParamList(out, getParamsAsyncLambda(p, package, true, true));
             out << ';';
diff --git a/cpp/src/slice2java/Gen.h b/cpp/src/slice2java/Gen.h
index 2617eb9905e..2c15bede991 100644
--- a/cpp/src/slice2java/Gen.h
+++ b/cpp/src/slice2java/Gen.h
@@ -43,7 +43,7 @@ protected:
     
     std::string getAsyncCallbackInterface(const OperationPtr&, const std::string&);
     std::string getAsyncCallbackBaseClass(const OperationPtr&, bool);
-    std::string getLambdaResposeCB(const OperationPtr&, const std::string&);
+    std::string getLambdaResponseCB(const OperationPtr&, const std::string&);
     std::vector<std::string> getParamsAsyncLambda(const OperationPtr&, const std::string&, 
                                                   bool context = false, bool sentCB = false, 
                                                   bool optionalMapping = false,
@@ -110,12 +110,14 @@ protected:
     static StringList splitComment(const ContainedPtr&);
     static void writeDocComment(::IceUtilInternal::Output&, const ContainedPtr&,
                                 const std::string&, const std::string& = "");
+    static void writeDocComment(::IceUtilInternal::Output&, const std::string&, const std::string&);
     static void writeDocCommentOp(::IceUtilInternal::Output&, const OperationPtr&);
 
     static void writeDocCommentAsync(::IceUtilInternal::Output&, const OperationPtr&,
                                      ParamDir, const std::string& = "");
     static void writeDocCommentAMI(::IceUtilInternal::Output&, const OperationPtr&, ParamDir, const std::string& = "",
-                                   const std::string& = "", const std::string& = "");
+                                   const std::string& = "", const std::string& = "", const std::string& = "",
+                                   const std::string& = "");
     static void writeDocCommentParam(::IceUtilInternal::Output&, const OperationPtr&, ParamDir, bool = true);
 };