ICE-6864 - C# fixes for doc comments on proxies

2 files changed, 168 insertions, 46 deletions

diff --git a/cpp/src/slice2cs/Gen.cpp b/cpp/src/slice2cs/Gen.cpp
index 89872c2e5c7..cf09aa9df1b 100644
--- a/cpp/src/slice2cs/Gen.cpp
+++ b/cpp/src/slice2cs/Gen.cpp
@@ -2466,9 +2466,128 @@ Slice::CsVisitor::writeDocCommentOp(const OperationPtr& p)
 }
 
 void
-Slice::CsVisitor::writeDocCommentAsync(const OperationPtr& p, ParamDir paramType, const string& extraParam, bool amd)
+Slice::CsVisitor::writeDocCommentAMI(const OperationPtr& p, ParamDir paramType, const string& deprecateReason,
+                                     const string& extraParam1, const string& extraParam2, const string& extraParam3)
+{
+    StringList summaryLines;
+    StringList remarksLines;
+    splitComment(p, summaryLines, remarksLines);
+
+    if(summaryLines.empty() && deprecateReason.empty())
+    {
+        return;
+    }
+
+    //
+    // Output the leading comment block up until the first tag.
+    //
+    _out << nl << "/// <summary>";
+    for(StringList::const_iterator i = summaryLines.begin(); i != summaryLines.end(); ++i)
+    {
+        _out << nl << "/// " << *i;
+    }
+
+    bool done = false;
+    for(StringList::const_iterator i = remarksLines.begin(); i != remarksLines.end() && !done; ++i)
+    {
+        string::size_type pos = i->find('<');
+        done = true;
+        if(pos != string::npos)
+        {
+            if(pos != 0)
+            {
+                _out << nl << "/// " << i->substr(0, pos);
+            }
+        }
+        else
+        {
+            _out << nl << "/// " << *i;
+        }
+    }
+    _out << nl << "/// </summary>";
+
+    //
+    // Write the comments for the parameters.
+    //
+    writeDocCommentParam(p, paramType, false);
+
+    if(!extraParam1.empty())
+    {
+        _out << nl << "/// " << extraParam1;
+    }
+
+    if(!extraParam2.empty())
+    {
+        _out << nl << "/// " << extraParam2;
+    }
+
+    if(!extraParam3.empty())
+    {
+        _out << nl << "/// " << extraParam3;
+    }
+
+    if(paramType == InParam)
+    {
+        _out << nl << "/// <returns>An asynchronous result object.</returns>";
+    }
+    else if(p->returnType())
+    {
+        //
+        // Find the comment for the return value (if any).
+        //
+        static const string returnsTag = "<returns>";
+        static const string returnsCloseTag = "</returns>";
+        bool doneReturn = false;
+        bool foundReturn = false;
+        for(StringList::const_iterator i = remarksLines.begin(); i != remarksLines.end() && !doneReturn; ++i)
+        {
+            if(!foundReturn)
+            {
+                string::size_type pos = i->find(returnsTag);
+                if(pos != string::npos)
+                {
+                    foundReturn = true;
+                    string::size_type endpos = i->find(returnsCloseTag, pos + 1);
+                    if(endpos != string::npos)
+                    {
+                        _out << nl << "/// " << i->substr(pos, endpos - pos + returnsCloseTag.size());
+                        doneReturn = true;
+                    }
+                    else
+                    {
+                        _out << nl << "/// " << i->substr(pos);
+                    }
+                }
+            }
+            else
+            {
+                string::size_type pos = i->find(returnsCloseTag);
+                if(pos != string::npos)
+                {
+                    _out << nl << "/// " << i->substr(0, pos + returnsCloseTag.size());
+                    doneReturn = true;
+                }
+                else
+                {
+                    _out << nl << "/// " << *i;
+                }
+            }
+        }
+        if(foundReturn && !doneReturn)
+        {
+            _out << returnsCloseTag;
+        }
+    }
+
+    if(!deprecateReason.empty())
+    {
+        _out << nl << "/// <para>" << deprecateReason << "</para>";
+    }
+}
+
+void
+Slice::CsVisitor::writeDocCommentAMD(const OperationPtr& p, ParamDir paramType, const string& extraParam)
 {
-    // TODO: this needs fixing for AMI (amd == false)
     ContainerPtr container = p->container();
     ClassDefPtr contained = ClassDefPtr::dynamicCast(container);
     string deprecateReason = getDeprecateReason(p, contained, "operation");
@@ -2482,16 +2601,12 @@ Slice::CsVisitor::writeDocCommentAsync(const OperationPtr& p, ParamDir paramType
         return;
     }
 
-
     if(paramType == OutParam)
     {
-        if(amd)
-        {
-            _out << nl << "/// <summary>";
-            _out << nl << "/// ice_response indicates that";
-            _out << nl << "/// the operation completed successfully.";
-            _out << nl << "/// </summary>";
-        }
+        _out << nl << "/// <summary>";
+        _out << nl << "/// ice_response indicates that";
+        _out << nl << "/// the operation completed successfully.";
+        _out << nl << "/// </summary>";
 
         //
         // Find the comment for the return value (if any) and rewrite that as a <param> comment.
@@ -2573,7 +2688,7 @@ Slice::CsVisitor::writeDocCommentAsync(const OperationPtr& p, ParamDir paramType
     //
     // Write the comments for the parameters.
     //
-    writeDocCommentParam(p, paramType, amd);
+    writeDocCommentParam(p, paramType, true);
 
     if(!extraParam.empty())
     {
@@ -4898,6 +5013,7 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
     ClassList bases = p->bases();
 
     _out << sp;
+    writeDocComment(p, getDeprecateReason(p, 0, p->isInterface() ? "interface" : "class"));
     emitGeneratedCodeAttribute();
     _out << nl << "public interface " << name << "Prx : ";
     if(bases.empty())
@@ -4937,36 +5053,28 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     ParamDeclList paramList = p->parameters();
     string retS = typeToString(p->returnType(), p->returnIsOptional());
 
-    _out << sp;
-
-    string deprecateMetadata, deprecateReason;
-    if(p->findMetaData("deprecate", deprecateMetadata) || cl->findMetaData("deprecate", deprecateMetadata))
-    {
-        deprecateReason = "This operation has been deprecated.";
-        if(deprecateMetadata.find("deprecate:") == 0 && deprecateMetadata.size() > 10)
-        {
-            deprecateReason = deprecateMetadata.substr(10);
-        }
-    }
-
-    // TODO: need to add doc comments for all of these.
+    string deprecateReason = getDeprecateReason(p, cl, "operation");
 
     //
-    // Write two versions of the operation - with and without a
-    // context parameter.
+    // Write two versions of the operation - with and without a context parameter.
     //
+    _out << sp;
+    writeDocComment(p, deprecateReason);
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
     }
     _out << nl << retS << " " << name << spar << params << epar << ';';
 
+    _out << sp;
+    writeDocComment(p, deprecateReason,
+        "<param name=\"ctx__\">The Context map to send with the invocation.</param>");
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
     }
     _out << nl << retS << " " << name << spar << params
-         << "_System.Collections.Generic.Dictionary<string, string> context__" << epar << ';';
+         << "_System.Collections.Generic.Dictionary<string, string> ctx__" << epar << ';';
 
     //
     // Write the operations for the new async mapping.
@@ -4976,16 +5084,20 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     string delType = clScope + "Callback_" + cl->name() + "_" + p->name();
 
     _out << sp;
+    writeDocCommentAMI(p, InParam, deprecateReason);
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
     }
     _out << nl << "Ice.AsyncResult<" << delType << "> begin_" << p->name() << spar << paramsNewAsync << epar << ';';
 
+    _out << sp;
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
     }
+    writeDocCommentAMI(p, InParam, deprecateReason,
+        "<param name=\"ctx__\">The Context map to send with the invocation.</param>");
     _out << nl << "Ice.AsyncResult<" << delType << "> begin_" << p->name() << spar << paramsNewAsync
          << "_System.Collections.Generic.Dictionary<string, string> ctx__" << epar << ';';
 
@@ -4993,6 +5105,9 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     // Type-unsafe begin_ methods.
     //
     _out << sp;
+    writeDocCommentAMI(p, InParam, deprecateReason,
+        "<param name=\"cb__\">Asynchronous callback invoked when the operation completes.</param>",
+        "<param name=\"cookie__\">Application data to store in the asynchronous result object.</param>");
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
@@ -5000,6 +5115,11 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     _out << nl << "Ice.AsyncResult begin_" << p->name() << spar << paramsNewAsync << "Ice.AsyncCallback cb__"
          << "object cookie__" << epar << ';';
 
+    _out << sp;
+    writeDocCommentAMI(p, InParam, deprecateReason,
+        "<param name=\"ctx__\">The Context map to send with the invocation.</param>",
+        "<param name=\"cb__\">Asynchronous callback invoked when the operation completes.</param>",
+        "<param name=\"cookie__\">Application data to store in the asynchronous result object.</param>");
     if(!deprecateReason.empty())
     {
         _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
@@ -5012,8 +5132,14 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     // end_ method.
     //
     _out << sp;
-    _out << nl << retS << " end_" << p->name() << spar << getParamsAsyncCB(p, false, true) << "Ice.AsyncResult r__" << epar
-         << ';';
+    writeDocCommentAMI(p, OutParam, deprecateReason,
+        "<param name=\"r__\">The asynchronous result object for the invocation.</param>");
+    if(!deprecateReason.empty())
+    {
+        _out << nl << "[_System.Obsolete(\"" << deprecateReason << "\")]";
+    }
+    _out << nl << retS << " end_" << p->name() << spar << getParamsAsyncCB(p, false, true) << "Ice.AsyncResult r__"
+         << epar << ';';
 }
 
 Slice::Gen::AsyncDelegateVisitor::AsyncDelegateVisitor(IceUtilInternal::Output& out)
@@ -5198,7 +5324,7 @@ Slice::Gen::OpsVisitor::writeOperations(const ClassDefPtr& p, bool noCurrent)
         }
         if(amd)
         {
-            writeDocCommentAsync(*r, InParam, extraCurrent, true);
+            writeDocCommentAMD(*r, InParam, extraCurrent);
         }
         else
         {
@@ -5256,7 +5382,6 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
     ClassList bases = p->bases();
 
     _out << sp;
-    writeDocComment(p, getDeprecateReason(p, 0, p->isInterface() ? "interface" : "class"));
     emitComVisibleAttribute();
     emitGeneratedCodeAttribute();
     _out << nl << "public sealed class " << name << "PrxHelper : Ice.ObjectPrxHelperBase, " << name << "Prx";
@@ -5314,7 +5439,6 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
 #endif
 
         _out << sp;
-        writeDocComment(op, deprecateReason);
         _out << nl << "public " << retS << " " << opName << spar << params << epar;
         _out << sb;
         _out << nl;
@@ -5326,17 +5450,15 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         _out << eb;
 
         _out << sp;
-        writeDocComment(op, deprecateReason,
-                        "<param name=\"context__\">The Context map to send with the invocation.</param>");
         _out << nl << "public " << retS << " " << opName << spar << params
-             << "_System.Collections.Generic.Dictionary<string, string> context__" << epar;
+             << "_System.Collections.Generic.Dictionary<string, string> ctx__" << epar;
         _out << sb;
         _out << nl;
         if(ret)
         {
             _out << "return ";
         }
-        _out << "this." << opName << spar << args << "context__" << "true" << epar << ';';
+        _out << "this." << opName << spar << args << "ctx__" << "true" << epar << ';';
         _out << eb;
 
         _out << sp << nl << "private " << retS << " " << opName << spar << params
@@ -5425,8 +5547,6 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         _out << eb;
 
         _out << sp;
-        writeDocCommentAsync(op, InParam,
-                             "<param name=\"ctx__\">The Context map to send with the invocation.</param>", false);
         _out << nl << "public Ice.AsyncResult<" << delType << "> begin_" << opName << spar << paramsAMI
              << "_System.Collections.Generic.Dictionary<string, string> ctx__" << epar;
         _out << sb;
@@ -5438,18 +5558,17 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         _out << nl << "public Ice.AsyncResult begin_" << opName << spar << paramsAMI
              << "Ice.AsyncCallback cb__" << "object cookie__" << epar;
         _out << sb;
-        _out << nl << "return begin_" << opName << spar << argsAMI << "null" << "false" << "false" << "cb__" << "cookie__"
-             << epar << ';';
+        _out << nl << "return begin_" << opName << spar << argsAMI << "null" << "false" << "false" << "cb__"
+             << "cookie__" << epar << ';';
         _out << eb;
 
         _out << sp;
-        // TODO writeDocCommentAsync(op, InParam, "", false);
         _out << nl << "public Ice.AsyncResult begin_" << opName << spar << paramsAMI
              << "_System.Collections.Generic.Dictionary<string, string> ctx__" << "Ice.AsyncCallback cb__"
              << "object cookie__" << epar;
         _out << sb;
-        _out << nl << "return begin_" << opName << spar << argsAMI << "ctx__" << "true" << "false" << "cb__" << "cookie__"
-             << epar << ';';
+        _out << nl << "return begin_" << opName << spar << argsAMI << "ctx__" << "true" << "false" << "cb__"
+             << "cookie__" << epar << ';';
         _out << eb;
 
         //
@@ -5592,7 +5711,8 @@ Slice::Gen::HelperVisitor::visitClassDefStart(const ClassDefPtr& p)
         _out << sp;
         _out << nl << "private Ice.AsyncResult<" << delType << "> begin_" << opName << spar << paramsAMI
              << "_System.Collections.Generic.Dictionary<string, string> ctx__"
-             << "bool explicitContext__" << "bool synchronous__" << "Ice.AsyncCallback cb__" << "object cookie__" << epar;
+             << "bool explicitContext__" << "bool synchronous__" << "Ice.AsyncCallback cb__" << "object cookie__"
+             << epar;
         _out << sb;
         if(op->returnsData())
         {
@@ -6414,7 +6534,7 @@ Slice::Gen::AsyncVisitor::visitOperation(const OperationPtr& p)
         _out << nl << "public interface " << classNameAMD << '_' << name << " : Ice.AMDCallback";
         _out << sb;
         _out << sp;
-        writeDocCommentAsync(p, OutParam, "", true);
+        writeDocCommentAMD(p, OutParam, "");
         _out << nl << "void ice_response" << spar << paramsAMD << epar << ';';
         _out << eb;
 
diff --git a/cpp/src/slice2cs/Gen.h b/cpp/src/slice2cs/Gen.h
index 78ad5e76c2f..a602ad33b78 100644
--- a/cpp/src/slice2cs/Gen.h
+++ b/cpp/src/slice2cs/Gen.h
@@ -66,7 +66,9 @@ protected:
     void writeDocCommentOp(const OperationPtr&);
 
     enum ParamDir { InParam, OutParam };
-    void writeDocCommentAsync(const OperationPtr&, ParamDir, const std::string&, bool);
+    void writeDocCommentAMI(const OperationPtr&, ParamDir, const std::string&, const std::string& = "",
+                            const std::string& = "", const std::string& = "");
+    void writeDocCommentAMD(const OperationPtr&, ParamDir, const std::string&);
     void writeDocCommentParam(const OperationPtr&, ParamDir, bool);
 
     ::IceUtilInternal::Output& _out;