Adding doc comments to C++

7 files changed, 2114 insertions, 740 deletions

diff --git a/cpp/src/Slice/Parser.cpp b/cpp/src/Slice/Parser.cpp
index 3b5cb054be2..ec9496f705d 100644
--- a/cpp/src/Slice/Parser.cpp
+++ b/cpp/src/Slice/Parser.cpp
@@ -280,6 +280,62 @@ Slice::DefinitionContext::initSuppressedWarnings()
 }
 
 // ----------------------------------------------------------------------
+// Comment
+// ----------------------------------------------------------------------
+
+bool
+Slice::Comment::isDeprecated() const
+{
+    return _isDeprecated;
+}
+
+StringList
+Slice::Comment::deprecated() const
+{
+    return _deprecated;
+}
+
+StringList
+Slice::Comment::overview() const
+{
+    return _overview;
+}
+
+StringList
+Slice::Comment::misc() const
+{
+    return _misc;
+}
+
+StringList
+Slice::Comment::seeAlso() const
+{
+    return _seeAlso;
+}
+
+StringList
+Slice::Comment::returns() const
+{
+    return _returns;
+}
+
+map<string, StringList>
+Slice::Comment::parameters() const
+{
+    return _parameters;
+}
+
+map<string, StringList>
+Slice::Comment::exceptions() const
+{
+    return _exceptions;
+}
+
+Slice::Comment::Comment()
+{
+}
+
+// ----------------------------------------------------------------------
 // SyntaxTreeBase
 // ----------------------------------------------------------------------
 
@@ -538,6 +594,330 @@ Slice::Contained::comment() const
     return _comment;
 }
 
+namespace
+{
+
+void
+trimLines(StringList& l)
+{
+    //
+    // Remove empty trailing lines.
+    //
+    while(!l.empty() && l.back().empty())
+    {
+        l.pop_back();
+    }
+}
+
+StringList
+splitComment(const string& c, bool stripMarkup)
+{
+    string comment = c;
+
+    if(stripMarkup)
+    {
+        //
+        // Strip HTML markup and javadoc links.
+        //
+        string::size_type pos = 0;
+        do
+        {
+            pos = comment.find('<', pos);
+            if(pos != string::npos)
+            {
+                string::size_type endpos = comment.find('>', pos);
+                if(endpos == string::npos)
+                {
+                    break;
+                }
+                comment.erase(pos, endpos - pos + 1);
+            }
+        }
+        while(pos != string::npos);
+
+        const string link = "{@link";
+        pos = 0;
+        do
+        {
+            pos = comment.find(link, pos);
+            if(pos != string::npos)
+            {
+                comment.erase(pos, link.size() + 1); // Erase trailing white space too.
+                string::size_type endpos = comment.find('}', pos);
+                if(endpos != string::npos)
+                {
+                    string ident = comment.substr(pos, endpos - pos);
+                    comment.erase(pos, endpos - pos + 1);
+
+                    //
+                    // Replace links of the form {@link Type#member} with "Type.member".
+                    //
+                    string::size_type hash = ident.find('#');
+                    string rest;
+                    if(hash != string::npos)
+                    {
+                        rest = ident.substr(hash + 1);
+                        ident = ident.substr(0, hash);
+                        if(!ident.empty())
+                        {
+                            if(!rest.empty())
+                            {
+                                ident += "." + rest;
+                            }
+                        }
+                        else if(!rest.empty())
+                        {
+                            ident = rest;
+                        }
+                    }
+
+                    comment.insert(pos, ident);
+                }
+            }
+        }
+        while(pos != string::npos);
+    }
+
+    StringList result;
+
+    string::size_type pos = 0;
+    string::size_type nextPos;
+    while((nextPos = comment.find_first_of('\n', pos)) != string::npos)
+    {
+        result.push_back(IceUtilInternal::trim(string(comment, pos, nextPos - pos)));
+        pos = nextPos + 1;
+    }
+    string lastLine = IceUtilInternal::trim(string(comment, pos));
+    if(!lastLine.empty())
+    {
+        result.push_back(lastLine);
+    }
+
+    trimLines(result);
+
+    return result;
+}
+
+bool
+parseCommentLine(const string& l, const string& tag, bool namedTag, string& name, string& doc)
+{
+    doc.clear();
+
+    if(l.find(tag) == 0)
+    {
+        const string ws = " \t";
+
+        if(namedTag)
+        {
+            string::size_type n = l.find_first_not_of(ws, tag.size());
+            if(n == string::npos)
+            {
+                return false; // Malformed line, ignore it.
+            }
+            string::size_type end = l.find_first_of(ws, n);
+            if(end == string::npos)
+            {
+                return false; // Malformed line, ignore it.
+            }
+            name = l.substr(n, end - n);
+            n = l.find_first_not_of(ws, end);
+            if(n != string::npos)
+            {
+                doc = l.substr(n);
+            }
+        }
+        else
+        {
+            name.clear();
+
+            string::size_type n = l.find_first_not_of(ws, tag.size());
+            if(n == string::npos)
+            {
+                return false; // Malformed line, ignore it.
+            }
+            doc = l.substr(n);
+        }
+
+        return true;
+    }
+
+    return false;
+}
+
+}
+
+CommentPtr
+Slice::Contained::parseComment(bool stripMarkup) const
+{
+    CommentPtr comment = new Comment;
+
+    comment->_isDeprecated = false;
+
+    //
+    // First check metadata for a deprecated tag.
+    //
+    string deprecateMetadata;
+    if(findMetaData("deprecate", deprecateMetadata))
+    {
+        comment->_isDeprecated = true;
+        if(deprecateMetadata.find("deprecate:") == 0 && deprecateMetadata.size() > 10)
+        {
+            comment->_deprecated.push_back(IceUtilInternal::trim(deprecateMetadata.substr(10)));
+        }
+    }
+
+    if(!comment->_isDeprecated && _comment.empty())
+    {
+        return 0;
+    }
+
+    //
+    // Split up the comment into lines.
+    //
+    StringList lines = splitComment(_comment, stripMarkup);
+
+    StringList::const_iterator i;
+    for(i = lines.begin(); i != lines.end(); ++i)
+    {
+        const string l = *i;
+        if(l[0] == '@')
+        {
+            break;
+        }
+        comment->_overview.push_back(l);
+    }
+
+    enum State { StateMisc, StateParam, StateThrows, StateReturn, StateDeprecated };
+    State state = StateMisc;
+    string name;
+    const string ws = " \t";
+    const string paramTag = "@param";
+    const string throwsTag = "@throws";
+    const string exceptionTag = "@exception";
+    const string returnTag = "@return";
+    const string deprecatedTag = "@deprecated";
+    const string seeTag = "@see";
+    for(; i != lines.end(); ++i)
+    {
+        const string l = IceUtilInternal::trim(*i);
+        string line;
+        if(parseCommentLine(l, paramTag, true, name, line))
+        {
+            if(!line.empty())
+            {
+                state = StateParam;
+                StringList sl;
+                sl.push_back(line); // The first line of the description.
+                comment->_parameters[name] = sl;
+            }
+        }
+        else if(parseCommentLine(l, throwsTag, true, name, line))
+        {
+            if(!line.empty())
+            {
+                state = StateThrows;
+                StringList sl;
+                sl.push_back(line); // The first line of the description.
+                comment->_exceptions[name] = sl;
+            }
+        }
+        else if(parseCommentLine(l, exceptionTag, true, name, line))
+        {
+            if(!line.empty())
+            {
+                state = StateThrows;
+                StringList sl;
+                sl.push_back(line); // The first line of the description.
+                comment->_exceptions[name] = sl;
+            }
+        }
+        else if(parseCommentLine(l, seeTag, false, name, line))
+        {
+            if(!line.empty())
+            {
+                comment->_seeAlso.push_back(line);
+            }
+        }
+        else if(parseCommentLine(l, returnTag, false, name, line))
+        {
+            if(!line.empty())
+            {
+                state = StateReturn;
+                comment->_returns.push_back(line); // The first line of the description.
+            }
+        }
+        else if(parseCommentLine(l, deprecatedTag, false, name, line))
+        {
+            comment->_isDeprecated = true;
+            if(!line.empty())
+            {
+                state = StateDeprecated;
+                comment->_deprecated.push_back(line); // The first line of the description.
+            }
+        }
+        else if(!l.empty())
+        {
+            if(l[0] == '@')
+            {
+                //
+                // Treat all other tags as miscellaneous comments.
+                //
+                state = StateMisc;
+            }
+
+            switch(state)
+            {
+                case StateMisc:
+                {
+                    comment->_misc.push_back(l);
+                    break;
+                }
+                case StateParam:
+                {
+                    assert(!name.empty());
+                    StringList sl;
+                    if(comment->_parameters.find(name) != comment->_parameters.end())
+                    {
+                        sl = comment->_parameters[name];
+                    }
+                    sl.push_back(l);
+                    comment->_parameters[name] = sl;
+                    break;
+                }
+                case StateThrows:
+                {
+                    assert(!name.empty());
+                    StringList sl;
+                    if(comment->_exceptions.find(name) != comment->_exceptions.end())
+                    {
+                        sl = comment->_exceptions[name];
+                    }
+                    sl.push_back(l);
+                    comment->_exceptions[name] = sl;
+                    break;
+                }
+                case StateReturn:
+                {
+                    comment->_returns.push_back(l);
+                    break;
+                }
+                case StateDeprecated:
+                {
+                    comment->_deprecated.push_back(l);
+                    break;
+                }
+            }
+        }
+    }
+
+    trimLines(comment->_overview);
+    trimLines(comment->_deprecated);
+    trimLines(comment->_misc);
+    trimLines(comment->_returns);
+
+    return comment;
+}
+
 int
 Slice::Contained::includeLevel() const
 {
diff --git a/cpp/src/Slice/Parser.h b/cpp/src/Slice/Parser.h
index 11cff96866e..b061c42fe2d 100644
--- a/cpp/src/Slice/Parser.h
+++ b/cpp/src/Slice/Parser.h
@@ -260,6 +260,43 @@ private:
 typedef ::IceUtil::Handle<DefinitionContext> DefinitionContextPtr;
 
 // ----------------------------------------------------------------------
+// Comment
+// ----------------------------------------------------------------------
+
+class Comment : public ::IceUtil::SimpleShared
+{
+public:
+
+    bool isDeprecated() const;
+    StringList deprecated() const;
+
+    StringList overview() const;  // Contains all introductory lines up to the first tag.
+    StringList misc() const;      // Contains unrecognized tags.
+    StringList seeAlso() const;   // Targets of @see tags.
+
+    StringList returns() const;                           // Description of an operation's return value.
+    std::map<std::string, StringList> parameters() const; // Parameter descriptions for an op. Key is parameter name.
+    std::map<std::string, StringList> exceptions() const; // Exception descriptions for an op. Key is exception name.
+
+private:
+
+    Comment();
+
+    bool _isDeprecated;
+    StringList _deprecated;
+    StringList _overview;
+    StringList _misc;
+    StringList _seeAlso;
+
+    StringList _returns;
+    std::map<std::string, StringList> _parameters;
+    std::map<std::string, StringList> _exceptions;
+
+    friend class Contained;
+};
+typedef ::IceUtil::Handle<Comment> CommentPtr;
+
+// ----------------------------------------------------------------------
 // GrammarBase
 // ----------------------------------------------------------------------
 
@@ -366,6 +403,7 @@ public:
     std::string file() const;
     std::string line() const;
     std::string comment() const;
+    CommentPtr parseComment(bool) const;
 
     int includeLevel() const;
     void updateIncludeLevel();
diff --git a/cpp/src/slice2cpp/Gen.cpp b/cpp/src/slice2cpp/Gen.cpp
index 94a3bd16f21..6631a261e1c 100644
--- a/cpp/src/slice2cpp/Gen.cpp
+++ b/cpp/src/slice2cpp/Gen.cpp
@@ -311,6 +311,293 @@ resultStructName(const string& name, const string& scope = "", bool marshaledRes
     return stName;
 }
 
+string
+condMove(bool moveIt, const string& str)
+{
+    return moveIt ? string("::std::move(") + str + ")" : str;
+}
+
+string
+escapeParam(const ParamDeclList& params, const string& name)
+{
+    string r = name;
+    for(ParamDeclList::const_iterator p = params.begin(); p != params.end(); ++p)
+    {
+        if(fixKwd((*p)->name()) == name)
+        {
+            r = name + "_";
+            break;
+        }
+    }
+    return r;
+}
+
+void
+writeDocLines(Output& out, const StringList& lines, bool commentFirst, const string& space = " ")
+{
+    StringList l = lines;
+    if(!commentFirst)
+    {
+        out << l.front();
+        l.pop_front();
+    }
+    for(StringList::const_iterator i = l.begin(); i != l.end(); ++i)
+    {
+        out << nl << " *";
+        if(!i->empty())
+        {
+            out << space << *i;
+        }
+    }
+}
+
+void
+writeSeeAlso(Output& out, const StringList& lines, const string& space = " ")
+{
+    for(StringList::const_iterator i = lines.begin(); i != lines.end(); ++i)
+    {
+        out << nl << " *";
+        if(!i->empty())
+        {
+            out << space << "@see " << *i;
+        }
+    }
+}
+
+string
+getDocSentence(const StringList& lines)
+{
+    //
+    // Extract the first sentence.
+    //
+    ostringstream ostr;
+    for(StringList::const_iterator i = lines.begin(); i != lines.end(); ++i)
+    {
+        const string ws = " \t";
+
+        if(i->empty())
+        {
+            break;
+        }
+        if(i != lines.begin() && i->find_first_not_of(ws) == 0)
+        {
+            ostr << " ";
+        }
+        string::size_type pos = i->find('.');
+        if(pos == string::npos)
+        {
+            ostr << *i;
+        }
+        else if(pos == i->size() - 1)
+        {
+            ostr << *i;
+            break;
+        }
+        else
+        {
+            //
+            // Assume a period followed by whitespace indicates the end of the sentence.
+            //
+            while(pos != string::npos)
+            {
+                if(ws.find((*i)[pos + 1]) != string::npos)
+                {
+                    break;
+                }
+                pos = i->find('.', pos + 1);
+            }
+            if(pos != string::npos)
+            {
+                ostr << i->substr(0, pos + 1);
+                break;
+            }
+            else
+            {
+                ostr << *i;
+            }
+        }
+    }
+
+    return ostr.str();
+}
+
+void
+writeDocSummary(Output& out, const ContainedPtr& p)
+{
+    if(p->comment().empty())
+    {
+        return;
+    }
+
+    CommentPtr doc = p->parseComment(false);
+
+    out << nl << "/**";
+
+    if(!doc->overview().empty())
+    {
+        writeDocLines(out, doc->overview(), true);
+    }
+
+    if(!doc->misc().empty())
+    {
+        writeDocLines(out, doc->misc(), true);
+    }
+
+    if(!doc->seeAlso().empty())
+    {
+        writeSeeAlso(out, doc->seeAlso());
+    }
+
+    if(!doc->deprecated().empty())
+    {
+        out << nl << " *";
+        out << nl << " * @deprecated ";
+        writeDocLines(out, doc->deprecated(), false);
+    }
+    else if(doc->isDeprecated())
+    {
+        out << nl << " *";
+        out << nl << " * @deprecated";
+    }
+
+    switch(p->containedType())
+    {
+        case Contained::ContainedTypeClass:
+        case Contained::ContainedTypeStruct:
+        case Contained::ContainedTypeException:
+        {
+            UnitPtr unit = p->container()->unit();
+            string file = p->file();
+            assert(!file.empty());
+            static const string prefix = "cpp:doxygen:include:";
+            DefinitionContextPtr dc = unit->findDefinitionContext(file);
+            assert(dc);
+            string q = dc->findMetaData(prefix);
+            if(!q.empty())
+            {
+                out << nl << " * \\headerfile " << q.substr(prefix.size());
+            }
+            break;
+        }
+        default:
+            break;
+    }
+
+    out << nl << " */";
+}
+
+enum OpDocParamType { OpDocInParams, OpDocOutParams, OpDocAllParams };
+
+void
+writeOpDocParams(Output& out, const OperationPtr& op, const CommentPtr& doc, OpDocParamType type,
+                 const StringList& preParams = StringList(), const StringList& postParams = StringList())
+{
+    ParamDeclList params;
+    switch(type)
+    {
+        case OpDocInParams:
+            params = op->inParameters();
+            break;
+        case OpDocOutParams:
+            params = op->outParameters();
+            break;
+        case OpDocAllParams:
+            params = op->parameters();
+            break;
+    }
+
+    if(!preParams.empty())
+    {
+        writeDocLines(out, preParams, true);
+    }
+
+    map<string, StringList> paramDoc = doc->parameters();
+    for(ParamDeclList::iterator p = params.begin(); p != params.end(); ++p)
+    {
+        map<string, StringList>::iterator q = paramDoc.find((*p)->name());
+        if(q != paramDoc.end())
+        {
+            out << nl << " * @param " << fixKwd(q->first) << " ";
+            writeDocLines(out, q->second, false);
+        }
+    }
+
+    if(!postParams.empty())
+    {
+        writeDocLines(out, postParams, true);
+    }
+}
+
+void
+writeOpDocExceptions(Output& out, const OperationPtr& op, const CommentPtr& doc)
+{
+    map<string, StringList> exDoc = doc->exceptions();
+    for(map<string, StringList>::iterator p = exDoc.begin(); p != exDoc.end(); ++p)
+    {
+        //
+        // Try to locate the exception's definition using the name given in the comment.
+        //
+        string name = p->first;
+        ExceptionPtr ex = op->container()->lookupException(name, false);
+        if(ex)
+        {
+            name = ex->scoped().substr(2);
+        }
+        out << nl << " * @throws " << name << " ";
+        writeDocLines(out, p->second, false);
+    }
+}
+
+void
+writeOpDocSummary(Output& out, const OperationPtr& op, const CommentPtr& doc, OpDocParamType type, bool showExceptions,
+                  const StringList& preParams = StringList(), const StringList& postParams = StringList(),
+                  const StringList& returns = StringList())
+{
+    out << nl << "/**";
+
+    if(!doc->overview().empty())
+    {
+        writeDocLines(out, doc->overview(), true);
+    }
+
+    writeOpDocParams(out, op, doc, type, preParams, postParams);
+
+    if(!returns.empty())
+    {
+        out << nl << " * @return ";
+        writeDocLines(out, returns, false);
+    }
+
+    if(showExceptions)
+    {
+        writeOpDocExceptions(out, op, doc);
+    }
+
+    if(!doc->misc().empty())
+    {
+        writeDocLines(out, doc->misc(), true);
+    }
+
+    if(!doc->seeAlso().empty())
+    {
+        writeSeeAlso(out, doc->seeAlso());
+    }
+
+    if(!doc->deprecated().empty())
+    {
+        out << nl << " *";
+        out << nl << " * @deprecated ";
+        writeDocLines(out, doc->deprecated(), false);
+    }
+    else if(doc->isDeprecated())
+    {
+        out << nl << " *";
+        out << nl << " * @deprecated";
+    }
+
+    out << nl << " */";
+}
+
 void
 emitOpNameResult(IceUtilInternal::Output& H, const OperationPtr& p, int useWstring)
 {
@@ -324,60 +611,59 @@ emitOpNameResult(IceUtilInternal::Output& H, const OperationPtr& p, int useWstri
     string retS = returnTypeToString(ret, p->returnIsOptional(), clScope, p->getMetaData(),
                                      useWstring | TypeContextCpp11);
 
-    ParamDeclList outParams;
-    ParamDeclList paramList = p->parameters();
-
-    for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q)
-    {
-        if((*q)->isOutParam())
-        {
-            outParams.push_back(*q);
-        }
-    }
+    ParamDeclList outParams = p->outParameters();
 
     if((outParams.size() > 1) || (ret && outParams.size() > 0))
     {
         //
         // Generate OpNameResult struct
         //
-        list<string> dataMembers;
         string returnValueS = "returnValue";
 
         for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q)
         {
-            string typeString = typeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(),
-                                             useWstring | TypeContextCpp11);
-
-            dataMembers.push_back(typeString + " " + fixKwd((*q)->name()));
-
             if((*q)->name() == "returnValue")
             {
                 returnValueS = "_returnValue";
             }
         }
 
-        if(ret)
-        {
-            dataMembers.push_front(retS + " " + returnValueS);
-        }
-
         H << sp;
+        H << nl << "/**";
+        H << nl << " * Encapsulates the results of a call to " << fixKwd(name) << ".";
+        H << nl << " */";
         H << nl << "struct " << resultStructName(name);
         H << sb;
-        for(list<string>::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
+        CommentPtr comment = p->parseComment(false);
+        map<string, StringList> paramComments;
+        if(comment)
+        {
+            paramComments = comment->parameters();
+        }
+        if(ret)
         {
-            H << nl << *q << ";";
+            if(comment && !comment->returns().empty())
+            {
+                H << nl << "/** " << getDocSentence(comment->returns()) << " */";
+            }
+            H << nl << retS << " " << returnValueS << ";";
+        }
+        for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q)
+        {
+            string typeString = typeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(),
+                                             useWstring | TypeContextCpp11);
+
+            map<string, StringList>::iterator r = paramComments.find((*q)->name());
+            if(r != paramComments.end())
+            {
+                H << nl << "/** " << getDocSentence(r->second) << " */";
+            }
+            H << nl << typeString << " " << fixKwd((*q)->name()) << ";";
         }
         H << eb << ";";
     }
 }
 
-string
-condMove(bool moveIt, const string& str)
-{
-    return moveIt ? string("::std::move(") + str + ")" : str;
-}
-
 }
 
 Slice::Gen::Gen(const string& base, const string& headerExtension, const string& sourceExtension,
@@ -971,15 +1257,31 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     DataMemberList allDataMembers = p->allDataMembers();
     bool hasDefaultValues = p->hasDefaultValues();
 
-    vector<string> allTypes;
     vector<string> allParamDecls;
     vector<string> baseParams;
+    map<string, CommentPtr> allComments;
+
+    string fileParam = "file";
+    string lineParam = "line";
 
     for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
     {
         string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring);
-        allTypes.push_back(typeName);
-        allParamDecls.push_back(typeName + " iceP_" + (*q)->name());
+        allParamDecls.push_back(typeName + " " + fixKwd((*q)->name()));
+        CommentPtr comment = (*q)->parseComment(false);
+        if(comment)
+        {
+            allComments[(*q)->name()] = comment;
+        }
+
+        if((*q)->name() == "file")
+        {
+            fileParam = "file_";
+        }
+        else if((*q)->name() == "line")
+        {
+            fileParam = "line_";
+        }
     }
 
     if(base)
@@ -987,11 +1289,13 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
         DataMemberList baseDataMembers = base->allDataMembers();
         for(DataMemberList::const_iterator q = baseDataMembers.begin(); q != baseDataMembers.end(); ++q)
         {
-            baseParams.push_back("iceP_" + (*q)->name());
+            baseParams.push_back(fixKwd((*q)->name()));
         }
     }
 
-    H << sp << nl << "class " << _dllExport << name << " : ";
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllExport << name << " : ";
     H.useCurrentPosAsIndent();
     H << "public ";
     if(base)
@@ -1009,10 +1313,27 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     H << nl << "public:";
     H.inc();
 
-    H << sp << nl << name << spar;
+    H << sp;
     if(p->isLocal())
     {
-        H << "const char*" << "int";
+        H << nl << "/**";
+        H << nl << " * The file and line number are required for all local exceptions.";
+        H << nl << " * @param " << fileParam
+          << " The file name in which the exception was raised, typically __FILE__.";
+        H << nl << " * @param " << lineParam
+          << " The line number at which the exception was raised, typically __LINE__.";
+        H << nl << " */";
+    }
+    else if(hasDefaultValues)
+    {
+        H << nl << "/** Default constructor that assigns default values to members as specified in the "
+          "Slice definition. */";
+    }
+
+    H << nl << name << spar;
+    if(p->isLocal())
+    {
+        H << "const char* " + fileParam << "int " + lineParam;
     }
     H << epar;
     if(!p->isLocal() && !hasDefaultValues)
@@ -1023,19 +1344,38 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     {
         H << ';';
     }
-    if(!allTypes.empty())
+    if(!allParamDecls.empty())
     {
+        H << nl << "/**";
+        H << nl << " * One-shot constructor to initialize all data members.";
+        if(p->isLocal())
+        {
+            H << nl << " * The file and line number are required for all local exceptions.";
+            H << nl << " * @param " << fileParam
+              << " The file name in which the exception was raised, typically __FILE__.";
+            H << nl << " * @param " << lineParam
+              << " The line number at which the exception was raised, typically __LINE__.";
+        }
+        for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
+        {
+            map<string, CommentPtr>::iterator r = allComments.find((*q)->name());
+            if(r != allComments.end())
+            {
+                H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview());
+            }
+        }
+        H << nl << " */";
         H << nl;
-        if(!p->isLocal() && allTypes.size() == 1)
+        if(!p->isLocal() && allParamDecls.size() == 1)
         {
             H << "explicit ";
         }
         H << name << spar;
         if(p->isLocal())
         {
-            H << "const char*" << "int";
+            H << "const char* " + fileParam << "int " + lineParam;
         }
-        H << allTypes << epar << ';';
+        H << allParamDecls << epar << ';';
     }
     H << nl << "virtual ~" << name << "() throw();";
     H << sp;
@@ -1055,10 +1395,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
 
     if(p->isLocal())
     {
-        C << sp << nl << scoped.substr(2) << "::" << name << spar << "const char* file_" << "int line_" << epar
-          << " :";
+        C << sp << nl << scoped.substr(2) << "::" << name << spar << "const char* " + fileParam
+          << "int " + lineParam << epar << " :";
         C.inc();
-        emitUpcall(base, "(file_, line_)", scope, true);
+        emitUpcall(base, "(" + fileParam + ", " + lineParam + ")", scope, true);
         if(p->hasDefaultValues())
         {
             C << ",";
@@ -1078,13 +1418,13 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
         C << eb;
     }
 
-    if(!allTypes.empty())
+    if(!allParamDecls.empty())
     {
         C << sp << nl;
         C << scoped.substr(2) << "::" << name << spar;
         if(p->isLocal())
         {
-            C << "const char* file_" << "int line_";
+            C << "const char* " + fileParam << "int " + lineParam;
         }
         C << allParamDecls << epar;
         if(p->isLocal() || !baseParams.empty() || !dataMembers.empty())
@@ -1097,7 +1437,7 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
                 upcall = "(";
                 if(p->isLocal())
                 {
-                    upcall += "file_, line_";
+                    upcall += fileParam + ", " + lineParam;
                 }
                 for(vector<string>::const_iterator pi = baseParams.begin(); pi != baseParams.end(); ++pi)
                 {
@@ -1121,7 +1461,8 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
             {
                 C << ",";
             }
-            C << nl << fixKwd((*d)->name()) << "(iceP_" << (*d)->name() << ')';
+            string memberName = fixKwd((*d)->name());
+            C << nl << memberName << "(" << memberName << ")";
         }
         if(p->isLocal() || !baseParams.empty() || !dataMembers.empty())
         {
@@ -1136,6 +1477,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     C << sb;
     C << eb;
 
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID of this exception.";
+    H << nl << " * @return The fully-scoped type ID.";
+    H << nl << " */";
     H << nl << "virtual ::std::string ice_id() const;";
     C << sp << nl << "::std::string" << nl << scoped.substr(2) << "::ice_id() const";
     C << sb;
@@ -1145,15 +1490,26 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     StringList metaData = p->getMetaData();
     if(find(metaData.begin(), metaData.end(), "cpp:ice_print") != metaData.end())
     {
-        H << nl << "virtual void ice_print(::std::ostream&) const;";
+        H << nl << "/**";
+        H << nl << " * Prints this exception to the given stream.";
+        H << nl << " * @param stream The target stream.";
+        H << nl << " */";
+        H << nl << "virtual void ice_print(::std::ostream& stream) const;";
     }
 
+    H << nl << "/**";
+    H << nl << " * Polymporphically clones this exception.";
+    H << nl << " * @return A shallow copy of this exception.";
+    H << nl << " */";
     H << nl << "virtual " << name << "* ice_clone() const;";
     C << sp << nl << scoped.substr(2) << "*" << nl << scoped.substr(2) << "::ice_clone() const";
     C << sb;
     C << nl << "return new " << name << "(*this);";
     C << eb;
 
+    H << nl << "/**";
+    H << nl << " * Throws this exception.";
+    H << nl << " */";
     H << nl << "virtual void ice_throw() const;";
     C << sp << nl << "void" << nl << scoped.substr(2) << "::ice_throw() const";
     C << sb;
@@ -1164,7 +1520,10 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     {
         if(!base || (base && !base->usesClasses(false)))
         {
-            H << sp << nl << "virtual bool _usesClasses() const;";
+            H << sp;
+            H << nl << "/// \\cond STREAM";
+            H << nl << "virtual bool _usesClasses() const;";
+            H << nl << "/// \\endcond";
 
             C << sp << nl << "bool";
             C << nl << scoped.substr(2) << "::_usesClasses() const";
@@ -1198,30 +1557,43 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         if(preserved && !basePreserved)
         {
             H << sp;
+            H << nl << "/**";
+            H << nl << " * Obtains the SlicedData object created when an unknown exception type was marshaled";
+            H << nl << " * in the sliced format and the Ice run time sliced it to a known type.";
+            H << nl << " * @return The SlicedData object, or nil if the exception was not sliced or was not";
+            H << nl << " * marshaled in the sliced format.";
+            H << nl << " */";
             H << nl << "virtual ::Ice::SlicedDataPtr ice_getSlicedData() const;";
 
             H << sp;
+            H << nl << "/// \\cond STREAM";
             H << nl << "virtual void _write(::Ice::OutputStream*) const;";
             H << nl << "virtual void _read(::Ice::InputStream*);";
 
             string baseName = base ? fixKwd(base->scoped()) : string("::Ice::UserException");
             H << nl << "using " << baseName << "::_write;";
             H << nl << "using " << baseName << "::_read;";
+            H << nl << "/// \\endcond";
         }
 
         H.dec();
         H << sp << nl << "protected:";
         H.inc();
 
-        H << sp << nl << "virtual void _writeImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;";
+        H << sp;
+        H << nl << "/// \\cond STREAM";
+        H << nl << "virtual void _writeImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;";
         H << nl << "virtual void _readImpl(" << getAbsolute("::Ice::InputStream*", scope) << ");";
+        H << nl << "/// \\endcond";
 
         string baseName = getAbsolute(base ? fixKwd(base->scoped()) : "::Ice::UserException", scope);
 
         if(preserved && !basePreserved)
         {
-
-            H << sp << nl << "::Ice::SlicedDataPtr _slicedData;";
+            H << sp;
+            H << nl << "/// \\cond STREAM";
+            H << nl << "::Ice::SlicedDataPtr _slicedData;";
+            H << nl << "/// \\endcond";
 
             C << sp;
             C << nl << "::Ice::SlicedDataPtr" << nl << scoped.substr(2) << "::ice_getSlicedData() const";
@@ -1246,7 +1618,9 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             C << eb;
         }
 
-        C << sp << nl << "void" << nl << scoped.substr(2) << "::_writeImpl("
+        C << sp;
+        C << nl << "/// \\cond STREAM";
+        C << nl << "void" << nl << scoped.substr(2) << "::_writeImpl("
           << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const";
         C << sb;
         C << nl << "ostr->startSlice(\"" << p->scoped() << "\", -1, " << (!base ? "true" : "false") << ");";
@@ -1271,6 +1645,7 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             emitUpcall(base, "::_readImpl(istr);", scope);
         }
         C << eb;
+        C << nl << "/// \\endcond";
     }
     H << eb << ';';
 
@@ -1284,7 +1659,10 @@ Slice::Gen::TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         if(!_doneStaticSymbol)
         {
             _doneStaticSymbol = true;
-            H << sp << nl << "static " << name << " _iceS_" << p->name() << "_init;";
+            H << sp;
+            H << nl << "/// \\cond INTERNAL";
+            H << nl << "static " << name << " _iceS_" << p->name() << "_init;";
+            H << nl << "/// \\endcond";
         }
     }
 
@@ -1299,10 +1677,13 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
     string scope = fixKwd(p->scope());
     string name = fixKwd(p->name());
 
+    H << sp;
+    writeDocSummary(H, p);
+
     bool classMetaData = findMetaData(p->getMetaData()) == "%class";
     if(classMetaData)
     {
-        H << sp << nl << "class " << name << " : public IceUtil::Shared";
+        H << nl << "class " << name << " : public IceUtil::Shared";
         H << sb;
         H.dec();
         H << nl << "public:";
@@ -1310,6 +1691,8 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
         H << nl;
         if(p->hasDefaultValues())
         {
+            H << nl << "/** Default constructor that assigns default values to members as specified in the "
+              "Slice definition. */";
             H << nl << name << "() :";
             H.inc();
             writeDataMemberInitializers(H, dataMembers, _useWstring);
@@ -1324,12 +1707,13 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
     }
     else
     {
-        H << sp << nl << "struct " << name;
+        H << nl << "struct " << name;
         H << sb;
         if(p->hasDefaultValues())
         {
+            H << nl << "/** Default constructor that assigns default values to members as specified in the "
+              "Slice definition. */";
             H << nl << name << "() :";
-
             H.inc();
             writeDataMemberInitializers(H, dataMembers, _useWstring);
             H.dec();
@@ -1345,12 +1729,32 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
     if(!dataMembers.empty() && (findMetaData(p->getMetaData()) == "%class" || p->hasDefaultValues()))
     {
         vector<string> paramDecls;
-        vector<string> types;
+        map<string, CommentPtr> comments;
         for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
         {
-            string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring);
-            types.push_back(typeName);
-            paramDecls.push_back(typeName + " iceP_" + (*q)->name());
+            string typeName =
+                inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring);
+            paramDecls.push_back(typeName + " " + fixKwd((*q)->name()));
+            CommentPtr comment = (*q)->parseComment(false);
+            if(comment && !comment->overview().empty())
+            {
+                comments[(*q)->name()] = comment;
+            }
+        }
+
+        if(!comments.empty())
+        {
+            H << nl << "/**";
+            H << nl << " * One-shot constructor to initialize all data members.";
+            for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
+            {
+                map<string, CommentPtr>::iterator r = comments.find((*q)->name());
+                if(r != comments.end())
+                {
+                    H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview());
+                }
+            }
+            H << nl << " */";
         }
 
         H << nl;
@@ -1368,7 +1772,7 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
                 H << ',';
             }
             string memberName = fixKwd((*q)->name());
-            H << nl << memberName << '(' << "iceP_" << (*q)->name() << ')';
+            H << nl << memberName << '(' << memberName << ')';
         }
 
         H.dec();
@@ -1482,6 +1886,8 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
     {
         scope = fixKwd(ex->scope());
     }
+
+    writeDocSummary(H, p);
     H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), _useWstring) << ' ' << name << ';';
 }
 
@@ -1498,6 +1904,8 @@ Slice::Gen::TypesVisitor::visitSequence(const SequencePtr& p)
     string seqType = findMetaData(metaData, _useWstring);
     H << sp;
 
+    writeDocSummary(H, p);
+
     if(!seqType.empty())
     {
         H << nl << "typedef " << seqType << ' ' << name << ';';
@@ -1516,6 +1924,9 @@ Slice::Gen::TypesVisitor::visitDictionary(const DictionaryPtr& p)
     string scope = fixKwd(cont->scope());
     string dictType = findMetaData(p->getMetaData());
 
+    H << sp;
+    writeDocSummary(H, p);
+
     if(dictType.empty())
     {
         //
@@ -1531,14 +1942,14 @@ Slice::Gen::TypesVisitor::visitDictionary(const DictionaryPtr& p)
         }
         string vs = typeToString(valueType, scope, p->valueMetaData(), _useWstring);
 
-        H << sp << nl << "typedef ::std::map<" << ks << ", " << vs << "> " << name << ';';
+        H << nl << "typedef ::std::map<" << ks << ", " << vs << "> " << name << ';';
     }
     else
     {
         //
         // A custom dictionary
         //
-        H << sp << nl << "typedef " << dictType << ' ' << name << ';';
+        H << nl << "typedef " << dictType << ' ' << name << ';';
     }
 }
 
@@ -1555,12 +1966,16 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p)
     //
     const bool explicitValue = p->explicitValue();
 
-    H << sp << nl << "enum " << name;
+    H << sp;
+    writeDocSummary(H, p);
+
+    H << nl << "enum " << name;
     H << sb;
 
     EnumeratorList::const_iterator en = enumerators.begin();
     while(en != enumerators.end())
     {
+        writeDocSummary(H, *en);
         H << nl << fixKwd(enumeratorPrefix + (*en)->name());
         //
         // If any of the enumerators were assigned an explicit value, we emit
@@ -1583,6 +1998,7 @@ Slice::Gen::TypesVisitor::visitConst(const ConstPtr& p)
 {
     string scope = fixKwd(p->scope());
     H << sp;
+    writeDocSummary(H, p);
     H << nl << "const " << typeToString(p->type(), scope, p->typeMetaData(), _useWstring) << " " << fixKwd(p->name())
       << " = ";
     writeConstantValue(H, p->type(), p->valueType(), p->value(), _useWstring, p->typeMetaData(), scope);
@@ -1666,9 +2082,11 @@ Slice::Gen::ProxyDeclVisitor::visitClassDecl(const ClassDeclPtr& p)
     // an interface named 'readProxy'
     // Note that _readProxy is always in the IceProxy::... namespace
     //
+    H << nl << "/// \\cond INTERNAL";
     H << nl << _dllExport << "void _readProxy(::Ice::InputStream*, ::IceInternal::ProxyHandle< ::IceProxy"
       << scoped << ">&);";
     H << nl << _dllExport << "::IceProxy::Ice::Object* upCast(::IceProxy" << scoped << "*);";
+    H << nl << "/// \\endcond";
 }
 
 Slice::Gen::ProxyVisitor::ProxyVisitor(Output& h, Output& c, const string& dllExport) :
@@ -1745,7 +2163,9 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
 
         string baseName = fixKwd("_" + p->name() + "Base");
 
-        H << sp << nl << "class " << _dllClassExport << baseName << " : ";
+        H << sp;
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "class " << _dllClassExport << baseName << " : ";
         H.useCurrentPosAsIndent();
         for(ClassList::const_iterator q = bases.begin(); q != bases.end();)
         {
@@ -1775,6 +2195,7 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
 
         H << sp << nl << "virtual Object* _newInstance() const = 0;";
         H << eb << ';';
+        H << nl << "/// \\endcond";
     }
 
     H << sp << nl << "class " << _dllClassExport << name << " : ";
@@ -1798,6 +2219,8 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
     H << nl << "public:";
     H.inc();
 
+    C << sp;
+    C << nl << "/// \\cond INTERNAL";
     C << nl
       << _dllExport
       << "::IceProxy::Ice::Object* ::IceProxy" << scope << "upCast(" << name << "* p) { return p; }";
@@ -1818,6 +2241,7 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
     C << nl << "v->_copyFrom(proxy);";
     C << eb;
     C << eb;
+    C << nl << "/// \\endcond";
 
     return true;
 }
@@ -1829,20 +2253,30 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
     string scoped = fixKwd(p->scoped());
     string scope = fixKwd(p->scope());
 
-    H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID corresponding to this " << (p->isInterface() ? "interface" : "class")
+      << ".";
+    H << nl << " * @return A fully-scoped type ID.";
+    H << nl << " */";
+    H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
 
     H.dec();
     H << sp << nl << "protected:";
     H.inc();
+    H << nl << "/// \\cond INTERNAL";
     H << sp << nl << _dllMemberExport << "virtual ::IceProxy::Ice::Object* _newInstance() const;";
+    H << nl << "/// \\endcond";
     H << eb << ';';
 
     C << sp;
+    C << nl << "/// \\cond INTERNAL";
     C << nl << "::IceProxy::Ice::Object*";
     C << nl << "IceProxy" << scoped << "::_newInstance() const";
     C << sb;
     C << nl << "return new " << name << ";";
     C << eb;
+    C << nl << "/// \\endcond";
 
     C << sp;
     C << nl << "const ::std::string&" << nl << "IceProxy" << scoped << "::ice_staticId()";
@@ -1897,7 +2331,8 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
     bool retIsOpt = p->returnIsOptional();
     string retS = returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIEnd);
-    string retSEndAMI = returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIPrivateEnd);
+    string retSEndAMI =
+        returnTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring | TypeContextAMIPrivateEnd);
     string retInS = retS != "void" ? inputTypeToString(ret, retIsOpt, "", p->getMetaData(), _useWstring) : "";
 
     ContainerPtr container = p->container();
@@ -1907,35 +2342,42 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     string delName = "Callback_" + clName + "_" + name;
     string delNameScoped = clScope + delName;
 
-    vector<string> params;
     vector<string> paramsDecl;
     vector<string> args;
 
     vector<string> paramsAMI;
     vector<string> paramsDeclAMI;
+    vector<string> paramsDeclAMIBeginI;
     vector<string> argsAMI;
     vector<string> outParamsAMI;
     vector<string> outParamNamesAMI;
     vector<string> outParamsDeclAMI;
+    vector<string> outParamsDeclImplAMI;
     vector<string> outParamsDeclEndAMI;
     vector<string> outDecls;
 
     ParamDeclList paramList = p->parameters();
-    ParamDeclList inParams;
-    ParamDeclList outParams;
+    ParamDeclList inParams = p->inParameters();
+    ParamDeclList outParams = p->outParameters();
+
+    const string contextParam = escapeParam(paramList, "context");
+    const string cbParam = escapeParam(inParams, "cb");
+    const string cookieParam = escapeParam(paramList, "cookie");
+    const string resultParam = escapeParam(outParams, "result");
 
     vector<string> outEndArgs;
 
     for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q)
     {
-        string paramName = fixKwd(paramPrefix + (*q)->name());
+        string paramName = fixKwd((*q)->name());
 
         StringList metaData = (*q)->getMetaData();
         string typeString;
         string typeStringEndAMI;
         if((*q)->isOutParam())
         {
-            typeString = outputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring | TypeContextAMIEnd);
+            typeString =
+                outputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring | TypeContextAMIEnd);
             typeStringEndAMI = outputTypeToString((*q)->type(), (*q)->optional(), "", metaData,
                                                   _useWstring | TypeContextAMIPrivateEnd);
         }
@@ -1944,7 +2386,6 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
             typeString = inputTypeToString((*q)->type(), (*q)->optional(), "", metaData, _useWstring);
         }
 
-        params.push_back(typeString);
         paramsDecl.push_back(typeString + ' ' + paramName);
         args.push_back(paramName);
 
@@ -1952,17 +2393,18 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         {
             paramsAMI.push_back(typeString);
             paramsDeclAMI.push_back(typeString + ' ' + paramName);
+            paramsDeclAMIBeginI.push_back(typeString + ' ' + paramPrefix + (*q)->name());
             argsAMI.push_back(paramName);
-            inParams.push_back(*q);
         }
         else
         {
             outParamsAMI.push_back(typeString);
             outParamNamesAMI.push_back(paramName);
             outParamsDeclAMI.push_back(typeString + ' ' + paramName);
-            outParamsDeclEndAMI.push_back(typeStringEndAMI + ' ' + paramName);
-            outParams.push_back(*q);
-            outDecls.push_back(inputTypeToString((*q)->type(), (*q)->optional(), "", (*q)->getMetaData(), _useWstring));
+            outParamsDeclImplAMI.push_back(typeString + ' ' + paramPrefix + (*q)->name());
+            outParamsDeclEndAMI.push_back(typeStringEndAMI + ' ' + paramPrefix + (*q)->name());
+            outDecls.push_back(
+                inputTypeToString((*q)->type(), (*q)->optional(), "", (*q)->getMetaData(), _useWstring));
             outEndArgs.push_back(getEndArg((*q)->type(), (*q)->getMetaData(), outParamNamesAMI.back()));
         }
     }
@@ -1987,61 +2429,147 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
     string thisPointer = fixKwd(scope.substr(0, scope.size() - 2)) + "*";
 
-    string deprecateSymbol = getDeprecateSymbol(p, cl);
-    H << sp << nl << deprecateSymbol << _dllMemberExport << retS << ' ' << fixKwd(name) << spar << paramsDecl
-      << "const ::Ice::Context& context = ::Ice::noExplicitContext" << epar;
+    CommentPtr comment = p->parseComment(false);
+    const string contextDoc = "@param " + contextParam + " The Context map to send with the invocation.";
+    const string contextDecl = "const ::Ice::Context& " + contextParam + " = ::Ice::noExplicitContext";
+    const string resultDoc = "The asynchronous result object for the invocation.";
+    const string cbDoc = "@param " + cbParam + " Asynchronous callback object.";
+    const string cookieDoc = "@param " + cookieParam + " User-defined data to associate with the invocation.";
+    const string cookieDecl = "const ::Ice::LocalObjectPtr& " + cookieParam + " = 0";
+
+    const string deprecateSymbol = getDeprecateSymbol(p, cl);
+    H << sp;
+    if(comment)
+    {
+        StringList postParams;
+        postParams.push_back(contextDoc);
+        writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns());
+    }
+    H << nl << deprecateSymbol << _dllMemberExport << retS << ' ' << fixKwd(name) << spar << paramsDecl
+      << contextDecl << epar;
     H << sb << nl;
     if(ret)
     {
         H << "return ";
     }
     H << "end_" << name << spar << outParamNamesAMI << "_iceI_begin_" + name << spar << argsAMI;
-    H << "context" << "::IceInternal::dummyCallback" << "0" << "true" << epar << epar << ';';
+    H << contextParam << "::IceInternal::dummyCallback" << "0" << "true" << epar << epar << ';';
     H << eb;
 
-    H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
-      << "const ::Ice::Context& context = ::Ice::noExplicitContext" << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(contextDoc);
+        returns.push_back(resultDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
+    H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI << contextDecl << epar;
     H << sb;
-    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "::IceInternal::dummyCallback" << "0"
+    H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << "::IceInternal::dummyCallback"
+      << "0"
       << epar << ';';
     H << eb;
 
-    H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
-      << "const ::Ice::CallbackPtr& del"
-      << "const ::Ice::LocalObjectPtr& cookie = 0" << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(cbDoc);
+        postParams.push_back(cookieDoc);
+        returns.push_back(resultDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
+    H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
+      << "const ::Ice::CallbackPtr& " + cbParam
+      << cookieDecl << epar;
     H << sb;
-    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << "del" << "cookie" << epar << ';';
+    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << cbParam << cookieParam
+      << epar << ';';
     H << eb;
 
-    H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
-      << "const ::Ice::Context& context"
-      << "const ::Ice::CallbackPtr& del"
-      << "const ::Ice::LocalObjectPtr& cookie = 0" << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(contextDoc);
+        postParams.push_back(cbDoc);
+        postParams.push_back(cookieDoc);
+        returns.push_back(resultDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
+    H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
+      << "const ::Ice::Context& " + contextParam
+      << "const ::Ice::CallbackPtr& " + cbParam
+      << cookieDecl << epar;
     H << sb;
-    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "del" << "cookie" << epar << ';';
+    H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << cbParam << cookieParam << epar
+      << ';';
     H << eb;
 
-    H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
-      << "const " + delNameScoped + "Ptr& del"
-      << "const ::Ice::LocalObjectPtr& cookie = 0" << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(cbDoc);
+        postParams.push_back(cookieDoc);
+        returns.push_back(resultDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
+    H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
+      << "const " + delNameScoped + "Ptr& " + cbParam
+      << cookieDecl << epar;
     H << sb;
-    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << "del" << "cookie" << epar << ';';
+    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "::Ice::noExplicitContext" << cbParam << cookieParam
+      << epar << ';';
     H << eb;
 
-    H << sp << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
-      << "const ::Ice::Context& context"
-      << "const " + delNameScoped + "Ptr& del"
-      << "const ::Ice::LocalObjectPtr& cookie = 0" << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(contextDoc);
+        postParams.push_back(cbDoc);
+        postParams.push_back(cookieDoc);
+        returns.push_back(resultDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
+    H << nl << "::Ice::AsyncResultPtr begin_" << name << spar << paramsDeclAMI
+      << "const ::Ice::Context& " + contextParam
+      << "const " + delNameScoped + "Ptr& " + cbParam
+      << cookieDecl << epar;
     H << sb;
-    H << nl << "return _iceI_begin_" << name << spar << argsAMI << "context" << "del" << "cookie" << epar << ';';
+    H << nl << "return _iceI_begin_" << name << spar << argsAMI << contextParam << cbParam << cookieParam << epar
+      << ';';
     H << eb;
 
-    H << sp << nl << _dllMemberExport << retS << " end_" << name << spar << outParamsDeclAMI
-      << "const ::Ice::AsyncResultPtr&" << epar << ';';
+    H << sp;
+    if(comment)
+    {
+        H << nl << "/**";
+        H << nl << " * Completes an invocation of begin_" << name << ".";
+        StringList postParams;
+        postParams.push_back("@param " + resultParam + " " + resultDoc);
+        writeOpDocParams(H, p, comment, OpDocOutParams, StringList(), postParams);
+        if(!comment->returns().empty())
+        {
+            H << nl << " * @return ";
+            writeDocLines(H, comment->returns(), false);
+        }
+        if(!comment->exceptions().empty())
+        {
+            writeOpDocExceptions(H, p, comment);
+        }
+        H << nl << " */";
+    }
+    H << nl << _dllMemberExport << retS << " end_" << name << spar << outParamsDeclAMI
+      << "const ::Ice::AsyncResultPtr& " + resultParam << epar << ';';
     if(generatePrivateEnd)
     {
+        H << nl << "/// \\cond INTERNAL";
         H << sp << nl << _dllMemberExport << "void _iceI_end_" << name << spar << outParamsDeclEndAMI;
         H << "const ::Ice::AsyncResultPtr&" << epar << ';';
+        H << nl << "/// \\endcond";
     }
 
     H.dec();
@@ -2058,7 +2586,8 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     H << nl << "public:";
     H.inc();
 
-    C << sp << nl << "::Ice::AsyncResultPtr" << nl << "IceProxy" << scope << "_iceI_begin_" << name << spar << paramsDeclAMI
+    C << sp << nl << "::Ice::AsyncResultPtr" << nl << "IceProxy" << scope << "_iceI_begin_" << name << spar
+      << paramsDeclAMIBeginI
       << "const ::Ice::Context& context" << "const ::IceInternal::CallbackBasePtr& del"
       << "const ::Ice::LocalObjectPtr& cookie" << "bool sync" << epar;
     C << sb;
@@ -2094,7 +2623,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     C << nl << "return result;";
     C << eb;
 
-    C << sp << nl << retS << nl << "IceProxy" << scope << "end_" << name << spar << outParamsDeclAMI
+    C << sp << nl << retS << nl << "IceProxy" << scope << "end_" << name << spar << outParamsDeclImplAMI
       << "const ::Ice::AsyncResultPtr& result" << epar;
     C << sb;
     if(p->returnsData())
@@ -2261,7 +2790,9 @@ Slice::Gen::ObjectDeclVisitor::visitClassDecl(const ClassDeclPtr& p)
         // upCast is not _upCast nor _iceUpCast for historical reasons. IceInternal::Handle
         // depends on this name
         //
+        H << nl << "/// \\cond INTERNAL";
         H << nl << _dllExport << getAbsolute("::Ice::Object*", scope) << " upCast(" << name << "*);";
+        H << nl << "/// \\endcond";
         H << nl << "typedef ::IceInternal::Handle< " << name << "> " << p->name() << "Ptr;";
         H << nl << "typedef ::IceInternal::ProxyHandle< ::IceProxy" << scoped << "> " << p->name() << "Prx;";
         H << nl << "typedef " << p->name() << "Prx " << p->name() << "PrxPtr;";
@@ -2270,13 +2801,17 @@ Slice::Gen::ObjectDeclVisitor::visitClassDecl(const ClassDeclPtr& p)
         // _ice prefix because this function is in the Slice module namespace, where the user
         // is allowed to define classes, functions etc. that start with _.
         //
+        H << nl << "/// \\cond INTERNAL";
         H << nl << _dllExport << "void _icePatchObjectPtr(" << p->name() << "Ptr&, const "
           << getAbsolute("::Ice::ObjectPtr&", scope) << ");";
+        H << nl << "/// \\endcond";
     }
     else
     {
+        H << nl << "/// \\cond INTERNAL";
         H << nl << _dllExport << getAbsolute("::Ice::LocalObject*", scope) << " upCast("
           << getAbsolute(scoped, scope) << "*);";
+        H << nl << "/// \\endcond";
         H << nl << "typedef ::IceInternal::Handle< " << name << "> " << p->name() << "Ptr;";
     }
 }
@@ -2342,7 +2877,9 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     bool basePreserved = p->inheritsMetaData("preserve-slice");
     bool preserved = basePreserved || p->hasMetaData("preserve-slice");
 
-    H << sp << nl << "class " << _dllExport << name << " : ";
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllExport << name << " : ";
     H.useCurrentPosAsIndent();
     if(bases.empty())
     {
@@ -2401,7 +2938,6 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     C << eb;
 
     vector<string> params;
-    vector<string> allTypes;
     vector<string> allParamDecls;
 
     for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
@@ -2412,15 +2948,17 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
     {
         string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring);
-        allTypes.push_back(typeName);
-        allParamDecls.push_back(typeName + " iceP_" + (*q)->name());
+        allParamDecls.push_back(typeName + " " + fixKwd((*q)->name()));
     }
 
     if(!p->isInterface())
     {
         if(p->hasDefaultValues())
         {
-            H << sp << nl << name << "() :";
+            H << sp;
+            H << nl << "/** Default constructor that assigns default values to members as specified in the "
+              "Slice definition. */";
+            H << nl << name << "() :";
             H.inc();
             writeDataMemberInitializers(H, dataMembers, _useWstring);
             H.dec();
@@ -2438,10 +2976,13 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
 
     if(!p->isLocal())
     {
-        C << sp << nl
+        C << sp;
+        C << nl << "/// \\cond INTERNAL";
+        C << nl
           << _dllExport
           << "::Ice::Object* " << scope.substr(2) << "upCast(" << name << "* p) { return p; }"
           << nl;
+        C << nl << "/// \\endcond";
 
         //
         // It would make sense to provide a covariant ice_clone(); unfortunately many compilers
@@ -2450,9 +2991,14 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
 
         if(!p->isInterface())
         {
-            H << sp << nl << "virtual " << getAbsolute("::Ice::ObjectPtr", scope) << " ice_clone() const;";
+            H << sp;
+            H << nl << "/**";
+            H << nl << " * Polymporphically clones this object.";
+            H << nl << " * @return A shallow copy of this object.";
+            H << nl << " */";
+            H << nl << "virtual " << getAbsolute("::Ice::ObjectPtr", scope) << " ice_clone() const;";
 
-             if(hasGCObjectBaseClass)
+            if(hasGCObjectBaseClass)
             {
                 C.zeroIndent();
                 C << sp;
@@ -2504,13 +3050,36 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
         StringList::difference_type scopedPos = IceUtilInternal::distance(firstIter, scopedIter);
 
         H << sp;
-        H << nl << "virtual bool ice_isA(const ::std::string&, const " << getAbsolute("::Ice::Current&", scope)
-          << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
+        H << nl << "/**";
+        H << nl << " * Determines whether this object supports an interface with the given Slice type ID.";
+        H << nl << " * @param id The fully-scoped Slice type ID.";
+        H << nl << " * @param current The Current object for the invocation.";
+        H << nl << " * @return True if this object supports the interface, false, otherwise.";
+        H << nl << " */";
+        H << nl << "virtual bool ice_isA(const ::std::string& id, const " << getAbsolute("::Ice::Current&", scope)
+          << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * Obtains a list of the Slice type IDs representing the interfaces supported by this object.";
+        H << nl << " * @param current The Current object for the invocation.";
+        H << nl << " * @return A list of fully-scoped type IDs.";
+        H << nl << " */";
         H << nl << "virtual ::std::vector< ::std::string> ice_ids(const " << getAbsolute("::Ice::Current&", scope)
-          << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
+          << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * Obtains a Slice type ID representing the most-derived interface supported by this object.";
+        H << nl << " * @param current The Current object for the invocation.";
+        H << nl << " * @return A fully-scoped type ID.";
+        H << nl << " */";
         H << nl << "virtual const ::std::string& ice_id(const " << getAbsolute("::Ice::Current&", scope)
-          << " = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
-        H << sp << nl << "static const ::std::string& ice_staticId();";
+          << " current = " << getAbsolute("::Ice::emptyCurrent", scope) << ") const;";
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * Obtains the Slice type ID corresponding to this class.";
+        H << nl << " * @return A fully-scoped type ID.";
+        H << nl << " */";
+        H << nl << "static const ::std::string& ice_staticId();";
 
         string flatName = "iceC" + p->flattenedScope() + p->name() + "_ids";
 
@@ -2573,9 +3142,13 @@ Slice::Gen::ObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     }
     else
     {
-        C << sp << nl
+        C << sp;
+        C << nl << "/// \\cond INTERNAL";
+        C << nl
           << _dllExport
-          << "::Ice::LocalObject* " << scope.substr(2) << "upCast(" << getAbsolute(scoped, scope) << "* p) { return p; }";
+          << "::Ice::LocalObject* " << scope.substr(2) << "upCast(" << getAbsolute(scoped, scope)
+          << "* p) { return p; }";
+        C << nl << "/// \\endcond";
     }
 
     return true;
@@ -2615,8 +3188,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             allOpNames.unique();
 
             H << sp;
+            H << nl << "/// \\cond INTERNAL";
             H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const "
               << getAbsolute("::Ice::Current&", scope) << ");";
+            H << nl << "/// \\endcond";
 
             string flatName = "iceC" + p->flattenedScope() + p->name() + "_all";
             C << sp << nl << "namespace";
@@ -2635,6 +3210,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             C << eb << ';';
             C << sp << nl << "}";
             C << sp;
+            C << nl << "/// \\cond INTERNAL";
             C << nl << "bool";
             C << nl << scoped.substr(2) << "::_iceDispatch(::IceInternal::Incoming& in, const "
               << getAbsolute("::Ice::Current&", scope) << " current)";
@@ -2667,6 +3243,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             C << eb;
             C << eb;
             C << eb;
+            C << nl << "/// \\endcond";
 
             //
             // Check if we need to generate ice_operationAttributes()
@@ -2684,8 +3261,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             if(!attributesMap.empty())
             {
                 H << sp;
+                H << nl << "/// \\cond INTERNAL";
                 H << nl << "virtual " << getAbsolute("::Ice::Int", scope)
                   << " ice_operationAttributes(const ::std::string&) const;";
+                H << nl << "/// \\endcond";
 
                 string opAttrFlatName = "iceC" + p->flattenedScope() + p->name() + "_operationAttributes";
 
@@ -2736,16 +3315,30 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
 
         if(!p->isAbstract())
         {
-            H << sp << nl << "static " << getAbsolute("::Ice::ValueFactoryPtr", scope) << " ice_factory();";
+            H << sp;
+            H << nl << "/**";
+            H << nl << " * Obtains a value factory that instantiates this class.";
+            H << nl << " * @return The value factory.";
+            H << nl << " */";
+            H << nl << "static " << getAbsolute("::Ice::ValueFactoryPtr", scope) << " ice_factory();";
         }
 
         if(preserved && !basePreserved)
         {
-            H << sp << nl << "virtual " << getAbsolute("::Ice::SlicedDataPtr", scope) << " ice_getSlicedData() const;";
+            H << sp;
+            H << nl << "/**";
+            H << nl << " * Obtains the SlicedData object created when an unknown class type was marshaled";
+            H << nl << " * in the sliced format and the Ice run time sliced it to a known type.";
+            H << nl << " * @return The SlicedData object, or nil if the class was not sliced or was not";
+            H << nl << " * marshaled in the sliced format.";
+            H << nl << " */";
+            H << nl << "virtual " << getAbsolute("::Ice::SlicedDataPtr", scope) << " ice_getSlicedData() const;";
 
             H << sp;
+            H << nl << "/// \\cond STREAM";
             H << nl << "virtual void _iceWrite(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;";
             H << nl << "virtual void _iceRead(" << getAbsolute("::Ice::InputStream*", scope) << ");";
+            H << nl << "/// \\endcond";
         }
 
         H.dec();
@@ -2753,8 +3346,11 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
         inProtected = true;
         H.inc();
 
-        H << sp << nl << "virtual void _iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;";
+        H << sp;
+        H << nl << "/// \\cond STREAM";
+        H << nl << "virtual void _iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope) << ") const;";
         H << nl << "virtual void _iceReadImpl(" << getAbsolute("::Ice::InputStream*", scope) << ");";
+        H << nl << "/// \\endcond";
 
         if(preserved && !basePreserved)
         {
@@ -2784,6 +3380,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
         }
 
         C << sp;
+        C << nl << "/// \\cond STREAM";
         C << nl << "void" << nl << scoped.substr(2) << "::_iceWriteImpl(" << getAbsolute("::Ice::OutputStream*", scope)
           << " ostr) const";
         C << sb;
@@ -2810,6 +3407,7 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             emitUpcall(base, "::_iceReadImpl(istr);", scope);
         }
         C << eb;
+        C << nl << "/// \\endcond";
 
         if(!p->isAbstract() || p->compactId() >= 0)
         {
@@ -2891,7 +3489,10 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
             H.inc();
             inProtected = true;
         }
-        H << sp << nl << "::Ice::SlicedDataPtr _iceSlicedData;";
+        H << sp;
+        H << nl << "/// \\cond STREAM";
+        H << nl << "::Ice::SlicedDataPtr _iceSlicedData;";
+        H << nl << "/// \\endcond";
     }
 
     if(generateFriend)
@@ -2920,27 +3521,36 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
         // But we do this only once per source file, because a single instance is sufficient to initialize
         // all of the globals in a compilation unit.
         //
-        H << nl << "static ::Ice::ValueFactoryPtr _iceS_" << p->name() << "_init = " << fixKwd(p->scoped()) << "::ice_factory();";
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "static ::Ice::ValueFactoryPtr _iceS_" << p->name() << "_init = " << fixKwd(p->scoped())
+          << "::ice_factory();";
+        H << nl << "/// \\endcond";
     }
 
     if(p->isLocal())
     {
         H << sp;
-        H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)";
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name())
+          << "& rhs)";
         H << sb;
         H << nl << "return static_cast<const " << getAbsolute("::Ice::LocalObject&", scope)
           << ">(lhs) == static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(rhs);";
         H << eb;
         H << sp;
-        H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)";
+        H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name())
+          << "& rhs)";
         H << sb;
         H << nl << "return static_cast<const " << getAbsolute("::Ice::LocalObject&", scope)
           << ">(lhs) < static_cast<const " << getAbsolute("::Ice::LocalObject&", scope) << ">(rhs);";
         H << eb;
+        H << nl << "/// \\endcond";
     }
     else
     {
-        C << sp << nl << "void";
+        C << sp;
+        C << nl << "/// \\cond INTERNAL";
+        C << nl << "void";
         C << nl << scope.substr(2) << "_icePatchObjectPtr(" << p->name() << "Ptr& handle, const "
           << getAbsolute("::Ice::ObjectPtr&", scope) << " v)";
         C << sb;
@@ -2950,19 +3560,24 @@ Slice::Gen::ObjectVisitor::visitClassDefEnd(const ClassDefPtr& p)
         C << nl << "IceInternal::Ex::throwUOE(" << name << "::ice_staticId(), v);";
         C << eb;
         C << eb;
+        C << nl << "/// \\endcond";
 
         H << sp;
-        H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)";
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "inline bool operator==(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name())
+          << "& rhs)";
         H << sb;
         H << nl << "return static_cast<const " << getAbsolute("::Ice::Object&", scope)
           << ">(lhs) == static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(rhs);";
         H << eb;
         H << sp;
-        H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name()) << "& rhs)";
+        H << nl << "inline bool operator<(const " << fixKwd(p->name()) << "& lhs, const " << fixKwd(p->name())
+          << "& rhs)";
         H << sb;
         H << nl << "return static_cast<const " << getAbsolute("::Ice::Object&", scope)
           << ">(lhs) < static_cast<const " << getAbsolute("::Ice::Object&", scope) << ">(rhs);";
         H << eb;
+        H << nl << "/// \\endcond";
     }
 
     _useWstring = resetUseWstring(_useWstringHist);
@@ -2996,32 +3611,37 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
     TypePtr ret = p->returnType();
     string retS = returnTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring);
 
+    ParamDeclList inParams = p->inParameters();
+    ParamDeclList outParams = p->outParameters();
+    ParamDeclList paramList = p->parameters();
+
+    const string cbParam = escapeParam(paramList, "cb");
+    const string cookieParam = escapeParam(paramList, "cookie");
+    const string resultParam = escapeParam(outParams, "result");
+    const string currentParam = escapeParam(paramList, "current");
+
     string params = "(";
     string paramsDecl = "(";
     string args = "(";
 
-    string paramsAMD = "(const " + classScopedAMD + '_' + name + "Ptr&, ";
+    string paramsAMD = "(const " + classScopedAMD + '_' + name + "Ptr& " + cbParam + ", ";
     string argsAMD = "(new IceAsync" + classScopedAMD + '_' + name + "(inS), ";
 
-    ParamDeclList inParams;
-    ParamDeclList outParams;
-    ParamDeclList paramList = p->parameters();
     vector< string> outDecls;
     for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q)
     {
-        string paramName = fixKwd(string(paramPrefix) + (*q)->name());
+        string paramName = fixKwd((*q)->name());
         TypePtr type = (*q)->type();
         bool isOutParam = (*q)->isOutParam();
         string typeString;
         if(isOutParam)
         {
-            outParams.push_back(*q);
             typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring);
         }
         else
         {
-            inParams.push_back(*q);
-            typeString = inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring);
+            typeString =
+                inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring);
         }
 
         if(q != paramList.begin())
@@ -3032,16 +3652,20 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
         }
 
         params += typeString;
+        params += ' ';
+        params += paramName;
         paramsDecl += typeString;
         paramsDecl += ' ';
         paramsDecl += paramName;
-        args += paramName;
+        args += paramPrefix + (*q)->name();
 
         if(!isOutParam)
         {
             paramsAMD += typeString;
+            paramsAMD += " ";
+            paramsAMD += paramName;
             paramsAMD += ", ";
-            argsAMD += paramName;
+            argsAMD += paramPrefix + (*q)->name();
             argsAMD += ", ";
         }
         else
@@ -3060,9 +3684,9 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
             args += ", ";
         }
 
-        params += "const " + getAbsolute("::Ice::Current&", classScope) + " = " +
+        params += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + " = " +
             getAbsolute("::Ice::emptyCurrent", classScope) + ")";
-        paramsDecl += "const " + getAbsolute("::Ice::Current&", classScope) + " current)";
+        paramsDecl += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + ")";
         args += "current)";
     }
     else
@@ -3072,7 +3696,7 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
         args += ')';
     }
 
-    paramsAMD += "const " + getAbsolute("::Ice::Current&", classScope) + " = " +
+    paramsAMD += "const " + getAbsolute("::Ice::Current&", classScope) + " " + currentParam + " = " +
         getAbsolute("::Ice::emptyCurrent", classScope) + ")";
     argsAMD += "current)";
 
@@ -3082,27 +3706,55 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
 
     string deprecateSymbol = getDeprecateSymbol(p, cl);
 
+    CommentPtr comment = p->parseComment(false);
+    const string cbDoc = "@param " + cbParam + " The AMD callback object for the invocation.";
+    const string currentDoc = "@param " + currentParam + " The Current object for the invocation.";
+    const string cookieDoc = "@param " + cookieParam + " Extra data to associate with the invocation.";
+    const string returnDoc = "The asynchronous result object for the invocation.";
+
     H << sp;
     if(!amd)
     {
+        if(comment)
+        {
+            StringList postParams;
+            if(!cl->isLocal())
+            {
+                postParams.push_back(currentDoc);
+            }
+            writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns());
+        }
+
         H << nl << deprecateSymbol
           << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept << " = 0;";
     }
     else
     {
+        if(comment)
+        {
+            StringList preParams, postParams;
+            preParams.push_back(cbDoc);
+            postParams.push_back(currentDoc);
+            StringList noReturns; // Leave empty - the AMD method has a void return type.
+            writeOpDocSummary(H, p, comment, OpDocInParams, true, preParams, postParams, noReturns);
+        }
+
         H << nl << deprecateSymbol
           << "virtual void " << name << "_async" << paramsAMD << isConst << noExcept << " = 0;";
     }
 
     if(!cl->isLocal())
     {
+        H << nl << "/// \\cond INTERNAL";
         H << nl << "bool _iceD_" << name << "(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", scope)
           << ")" << isConst << ';';
+        H << nl << "/// \\endcond";
 
         C << sp;
         //
         // inS, ret, current etc. may shadow class-with-operations data members in C++98
         //
+        C << nl << "/// \\cond INTERNAL";
         C << nl << "bool" << nl << scope.substr(2) << "_iceD_" << name << "(::IceInternal::Incoming& inS"
           << ", const " << getAbsolute("::Ice::Current&", classScope) << " current)" << isConst;
         C << sb;
@@ -3159,6 +3811,7 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
             C << nl << "return false;";
         }
         C << eb;
+        C << nl << "/// \\endcond";
     }
 
     if(cl->isLocal() && (cl->hasMetaData("async-oneway") || p->hasMetaData("async-oneway")))
@@ -3193,24 +3846,58 @@ Slice::Gen::ObjectVisitor::visitOperation(const OperationPtr& p)
             }
         }
 
-        H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
+        H << sp;
+        if(comment)
+        {
+            StringList returns;
+            returns.push_back(returnDoc);
+            writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), StringList(), returns);
+        }
+        H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
           << paramsDeclAMI << epar << " = 0;";
 
-        H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
+        H << sp;
+        if(comment)
+        {
+            StringList postParams, returns;
+            postParams.push_back("@param " + cbParam + " Callback to be invoked when the invocation completes");
+            postParams.push_back(cookieDoc);
+            returns.push_back(returnDoc);
+            writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+        }
+        H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
           << paramsDeclAMI
-          << ("const " + getAbsolute("::Ice::CallbackPtr&", classScope) + " del")
-          << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " cookie = 0")
+          << ("const " + getAbsolute("::Ice::CallbackPtr&", classScope) + " " + cbParam)
+          << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " " + cookieParam + " = 0")
           << epar << " = 0;";
 
         string delName = "Callback_" + cl->name() + "_" + name;
 
-        H << sp << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
+        H << sp;
+        if(comment)
+        {
+            StringList postParams, returns;
+            postParams.push_back("@param " + cbParam + " Callback to be invoked when the invocation completes");
+            postParams.push_back(cookieDoc);
+            returns.push_back(returnDoc);
+            writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+        }
+        H << nl << "virtual " << getAbsolute("::Ice::AsyncResultPtr", classScope) << " begin_" << name << spar
           << paramsDeclAMI
-          << ("const " + delName + "Ptr& del")
-          << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " cookie = 0") << epar << " = 0;";
+          << ("const " + delName + "Ptr& " + cbParam)
+          << ("const " + getAbsolute("::Ice::LocalObjectPtr&", classScope) + " " + cookieParam + " = 0") << epar
+          << " = 0;";
 
-        H << sp << nl << "virtual " << retS << " end_" << name << spar << outParamsDeclAMI
-          << ("const " + getAbsolute("::Ice::AsyncResultPtr&", classScope)) << epar << " = 0;";
+        H << sp;
+        if(comment)
+        {
+            StringList postParams, returns;
+            postParams.push_back("@param " + resultParam +
+                                 " The asynchronous result object returned by the begin_ method.");
+            writeOpDocSummary(H, p, comment, OpDocOutParams, true, StringList(), postParams, comment->returns());
+        }
+        H << nl << "virtual " << retS << " end_" << name << spar << outParamsDeclAMI
+          << ("const " + getAbsolute("::Ice::AsyncResultPtr&", classScope) + " " + resultParam) << epar << " = 0;";
     }
 }
 
@@ -3221,6 +3908,7 @@ Slice::Gen::ObjectVisitor::emitDataMember(const DataMemberPtr& p)
     ContainerPtr container = p->container();
     ClassDefPtr cl = ClassDefPtr::dynamicCast(container);
     int typeContext = cl->isLocal() ? TypeContextLocal | _useWstring : _useWstring;
+    writeDocSummary(H, p);
     H << nl << typeToString(p->type(), p->optional(), fixKwd(cl->scope()), p->getMetaData(), typeContext) << ' '
       << name << ';';
 }
@@ -3255,7 +3943,9 @@ Slice::Gen::ObjectVisitor::emitGCFunctions(const ClassDefPtr& p)
     //
     if(canBeCyclic || (preserved && !basePreserved))
     {
+        H << nl << "/// \\cond INTERNAL";
         H << nl << "virtual void _iceGcVisitMembers(::IceInternal::GCVisitor&);";
+        H << nl << "/// \\endcond";
 
         C << sp << nl << "void" << nl << scoped.substr(2) << "::_iceGcVisitMembers(::IceInternal::GCVisitor& v_)";
         C << sb;
@@ -3397,7 +4087,7 @@ Slice::Gen::ObjectVisitor::emitVirtualBaseInitializers(const ClassDefPtr& p, boo
         {
             upcall += ", ";
         }
-        upcall += "iceP_" + (*q)->name();
+        upcall += fixKwd((*q)->name());
     }
     upcall += ")";
 
@@ -3415,29 +4105,48 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
     if(!allDataMembers.empty())
     {
         vector<string> allParamDecls;
+        map<string, CommentPtr> allComments;
 
         bool virtualInheritance = p->hasMetaData("cpp:virtual");
-        bool callBaseConstuctors = !(p->isAbstract() && virtualInheritance);
+        bool callBaseConstructors = !(p->isAbstract() && virtualInheritance);
         DataMemberList dataMembers = p->dataMembers();
 
         int typeContext = p->isLocal() ? (_useWstring | TypeContextLocal) : _useWstring;
 
         for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
         {
-
-            string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext);
+            string typeName =
+                inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext);
             bool dataMember = std::find(dataMembers.begin(), dataMembers.end(), (*q)) != dataMembers.end();
-            allParamDecls.push_back(typeName + ((dataMember || callBaseConstuctors) ?
-                                                    (" iceP_" + (*q)->name()) : (" /*iceP_" + (*q)->name() + "*/")));
+            allParamDecls.push_back(typeName + ((dataMember || callBaseConstructors) ?
+                                                    (" " + fixKwd((*q)->name())) :
+                                                    (" /*" + fixKwd((*q)->name()) + "*/")));
+            CommentPtr comment = (*q)->parseComment(false);
+            if(comment)
+            {
+                allComments[(*q)->name()] = comment;
+            }
         }
 
-        H << sp << nl;
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * One-shot constructor to initialize all data members.";
+        for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
+        {
+            map<string, CommentPtr>::iterator r = allComments.find((*q)->name());
+            if(r != allComments.end())
+            {
+                H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview());
+            }
+        }
+        H << nl << " */";
+        H << nl;
         if(allParamDecls.size() == 1)
         {
             H << "explicit ";
         }
         H << fixKwd(p->name()) << spar << allParamDecls << epar;
-        if(callBaseConstuctors || !dataMembers.empty())
+        if(callBaseConstructors || !dataMembers.empty())
         {
             H << " :";
         }
@@ -3446,7 +4155,7 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
         ClassList bases = p->bases();
         ClassDefPtr base;
 
-        if(!bases.empty() && !bases.front()->isInterface() && callBaseConstuctors)
+        if(!bases.empty() && !bases.front()->isInterface() && callBaseConstructors)
         {
             if(emitVirtualBaseInitializers(bases.front(), virtualInheritance, true))
             {
@@ -3468,7 +4177,7 @@ Slice::Gen::ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
                 H << ',' << nl;
             }
             string memberName = fixKwd((*q)->name());
-            H << memberName << '(' << "iceP_" << (*q)->name() << ')';
+            H << memberName << '(' << memberName << ')';
         }
 
         H.dec();
@@ -3547,7 +4256,13 @@ Slice::Gen::AsyncCallbackVisitor::visitOperation(const OperationPtr& p)
     // Write the callback base class and callback smart pointer.
     //
     string delName = "Callback_" + cl->name() + "_" + p->name();
-    H << sp << nl << "class " << delName << "_Base : public virtual ::IceInternal::CallbackBase { };";
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Base class for asynchronous callback wrapper classes used for calls to";
+    H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << ".";
+    H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << ".";
+    H << nl << " */";
+    H << nl << "class " << delName << "_Base : public virtual ::IceInternal::CallbackBase { };";
     H << nl << "typedef ::IceUtil::Handle< " << delName << "_Base> " << delName << "Ptr;";
 }
 
@@ -3640,22 +4355,34 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr&
             outParams.push_back(*q);
             outArgs.push_back("iceP_" + (*q)->name());
             outEndArgs.push_back(getEndArg((*q)->type(), (*q)->getMetaData(), outArgs.back()));
-            outDecls.push_back(inputTypeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), _useWstring));
+            outDecls.push_back(
+                inputTypeToString((*q)->type(), (*q)->optional(), clScope, (*q)->getMetaData(), _useWstring));
         }
     }
 
+    H << sp;
     string baseD;
     string inheritD;
     if(withCookie)
     {
         baseD = "::IceInternal::Callback<T, CT>";
-        H << sp << nl << "template<class T, typename CT>";
+        H << nl << "/**";
+        H << nl << " * Type-safe asynchronous callback wrapper class with cookie support used for calls to";
+        H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << ".";
+        H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << ".";
+        H << nl << " */";
+        H << nl << "template<class T, typename CT>";
         inheritD = p->returnsData() ? "::IceInternal::TwowayCallback<T, CT>" : "::IceInternal::OnewayCallback<T, CT>";
     }
     else
     {
         baseD = "::IceInternal::CallbackNC<T>";
-        H << sp << nl << "template<class T>";
+        H << nl << "/**";
+        H << nl << " * Type-safe asynchronous callback wrapper class used for calls to";
+        H << nl << " * IceProxy" << fixKwd(cl->scoped()) << "::begin_" << p->name() << ".";
+        H << nl << " * Create a wrapper instance by calling " << fixKwd(cl->scope()) << "new" << delName << ".";
+        H << nl << " */";
+        H << nl << "template<class T>";
         inheritD = p->returnsData() ? "::IceInternal::TwowayCallbackNC<T>" : "::IceInternal::OnewayCallbackNC<T>";
     }
 
@@ -3725,11 +4452,14 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr&
         //
         // completed.
         //
-        H << sp << nl << "virtual void completed(const " << getAbsolute("::Ice::AsyncResultPtr&", clScope)
+        H << sp;
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "virtual void completed(const " << getAbsolute("::Ice::AsyncResultPtr&", clScope)
           << " result) const";
         H << sb;
         H << nl << clName << "Prx proxy = " << clName << "Prx::uncheckedCast(result->getProxy());";
-        writeAllocateCode(H, outParams, p, true, clScope, _useWstring | TypeContextInParam | TypeContextAMICallPrivateEnd);
+        writeAllocateCode(H, outParams, p, true, clScope,
+                          _useWstring | TypeContextInParam | TypeContextAMICallPrivateEnd);
         H << nl << "try";
         H << sb;
         H << nl;
@@ -3773,6 +4503,7 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr&
         H << epar << ';';
         H << eb;
         H << eb;
+        H << nl << "/// \\endcond";
         H.dec();
         H << sp << nl << "private:";
         H.inc();
@@ -3785,15 +4516,29 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr&
     {
         string callbackT = i == 0 ? "const IceUtil::Handle<T>&" : "T*";
 
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * Creates a callback wrapper instance that delegates to your object.";
+        if(withCookie)
+        {
+            H << nl << " * Use this overload when your callback methods receive a cookie value.";
+        }
+        H << nl << " * @param instance The callback object.";
+        H << nl << " * @param cb The success method of the callback object.";
+        H << nl << " * @param excb The exception method of the callback object.";
+        H << nl << " * @param sentcb The sent method of the callback object.";
+        H << nl << " * @return An object that can be passed to an asynchronous invocation of IceProxy"
+          << clScope << clName << "::begin_" << p->name() << ".";
+        H << nl << " */";
         if(withCookie)
         {
             cookieT = "const CT&";
             comCookieT = ", const CT&";
-            H << sp << nl << "template<class T, typename CT> " << delName << "Ptr";
+            H << nl << "template<class T, typename CT> " << delName << "Ptr";
         }
         else
         {
-            H << sp << nl << "template<class T> " << delName << "Ptr";
+            H << nl << "template<class T> " << delName << "Ptr";
         }
 
         H << nl << "new" << delName << "(" << callbackT << " instance, ";
@@ -3830,13 +4575,26 @@ Slice::Gen::AsyncCallbackTemplateVisitor::generateOperation(const OperationPtr&
 
         if(!ret && outParams.empty())
         {
+            H << sp;
+            H << nl << "/**";
+            H << nl << " * Creates a callback wrapper instance that delegates to your object.";
             if(withCookie)
             {
-                H << sp << nl << "template<class T, typename CT> " << delName << "Ptr";
+                H << nl << " * Use this overload when your callback methods receive a cookie value.";
+            }
+            H << nl << " * @param instance The callback object.";
+            H << nl << " * @param excb The exception method of the callback object.";
+            H << nl << " * @param sentcb The sent method of the callback object.";
+            H << nl << " * @return An object that can be passed to an asynchronous invocation of IceProxy"
+              << clScope << clName << "::begin_" << p->name() << ".";
+            H << nl << " */";
+            if(withCookie)
+            {
+                H << nl << "template<class T, typename CT> " << delName << "Ptr";
             }
             else
             {
-                H << sp << nl << "template<class T> " << delName << "Ptr";
+                H << nl << "template<class T> " << delName << "Ptr";
             }
             H << nl << "new" << delName << "(" << callbackT << " instance, ";
             H << "void (T::*excb)(" << "const ::Ice::Exception&" << comCookieT << "), ";
@@ -4201,79 +4959,81 @@ Slice::Gen::AsyncVisitor::visitOperation(const OperationPtr& p)
     string classNameAMD = "AMD_" + className;
     string classScope = fixKwd(cl->scope());
     string classScopedAMD = classScope + classNameAMD;
-    string proxyName = classScope + className + "Prx";
-
-    vector<string> params;
-    vector<string> paramsAMD;
-    vector<string> paramsDecl;
-    vector<string> args;
-
-    vector<string> paramsInvoke;
-
-    paramsInvoke.push_back("const " + proxyName + "&");
 
     TypePtr ret = p->returnType();
     string retS = inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring);
 
+    string resultParam = "result";
+    ParamDeclList paramList = p->outParameters();
+    for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q)
+    {
+        if((*q)->name() == "result")
+        {
+            resultParam = "result_";
+            break;
+        }
+    }
+
+    vector<string> paramsAMD;
+
     if(ret)
     {
-        params.push_back(retS);
-        paramsAMD.push_back(inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring));
-        paramsDecl.push_back(retS + " ret");
-        args.push_back("ret");
+        paramsAMD.push_back(inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(), _useWstring) +
+                            " " + resultParam);
     }
 
-    ParamDeclList inParams;
-    ParamDeclList outParams;
-    ParamDeclList paramList = p->parameters();
     for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q)
     {
         string paramName = fixKwd((*q)->name());
         TypePtr type = (*q)->type();
         string typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring);
-
-        if((*q)->isOutParam())
-        {
-            params.push_back(typeString);
-            paramsAMD.push_back(inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), _useWstring));
-            paramsDecl.push_back(typeString + ' ' + paramName);
-            args.push_back(paramName);
-
-            outParams.push_back(*q);
-        }
-        else
-        {
-            paramsInvoke.push_back(typeString);
-            inParams.push_back(*q);
-        }
+        paramsAMD.push_back(typeString + " " + paramName);
     }
 
-    paramsInvoke.push_back(getAbsolute("const ::Ice::Context&", classScope));
+    string cbName = classNameAMD + '_' + name;
 
-    if(cl->hasMetaData("amd") || p->hasMetaData("amd"))
-    {
-        string cbName = classNameAMD + '_' + name;
+    CommentPtr comment = p->parseComment(false);
 
-        H << sp << nl << "class " << _dllExport << cbName << " : public virtual "
-          << getAbsolute("::Ice::AMDCallback", classScope);
-        H << sb;
-        H.dec();
-        H << nl << "public:";
-        H.inc();
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * AMD callback class for " << fixKwd(p->scoped()).substr(2) << "_async.";
+    H << nl << " * Call the ice_response method for a successful completion, or the ice_exception";
+    H << nl << " * method in the case of an error.";
+    H << nl << " */";
+    H << nl << "class " << _dllExport << cbName << " : public virtual "
+      << getAbsolute("::Ice::AMDCallback", classScope);
+    H << sb;
+    H.dec();
+    H << nl << "public:";
+    H.inc();
 
-        // Out of line dtor to avoid weak vtable
-        H << sp << nl << "virtual ~" << cbName << "();";
-        C << sp;
-        C << nl << classScope.substr(2) << cbName << "::~" << cbName << "()";
-        C << sb;
-        C << eb;
+    // Out of line dtor to avoid weak vtable
+    H << sp << nl << "virtual ~" << cbName << "();";
+    C << sp;
+    C << nl << classScope.substr(2) << cbName << "::~" << cbName << "()";
+    C << sb;
+    C << eb;
 
-        H << sp;
-        H << nl << "virtual void ice_response" << spar << paramsAMD << epar << " = 0;";
-        H << eb << ';';
-        H << sp << nl << "typedef ::IceUtil::Handle< " << classScopedAMD << '_' << name << "> "
-          << classNameAMD << '_' << name  << "Ptr;";
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Call ice_response for a successful completion.";
+    if(comment)
+    {
+        StringList preParams;
+        StringList returns = comment->returns();
+        if(ret && !returns.empty())
+        {
+            preParams = returns;
+            preParams.pop_front();
+            preParams.push_front("@param " + resultParam + " " + returns.front());
+        }
+        writeOpDocParams(H, p, comment, OpDocOutParams, preParams);
     }
+    H << nl << " */";
+    H << nl << "virtual void ice_response" << spar << paramsAMD << epar << " = 0;";
+    H << eb << ';';
+    H << sp << nl << "typedef ::IceUtil::Handle< " << classScopedAMD << '_' << name << "> "
+      << classNameAMD << '_' << name  << "Ptr;";
 }
 
 Slice::Gen::AsyncImplVisitor::AsyncImplVisitor(Output& h, Output& c, const string& dllExport) :
@@ -4289,7 +5049,9 @@ Slice::Gen::AsyncImplVisitor::visitUnitStart(const UnitPtr& p)
         return false;
     }
 
-    H << sp << nl << "namespace IceAsync" << nl << '{';
+    H << sp;
+    H << nl << "/// \\cond INTERNAL";
+    H << nl << "namespace IceAsync" << nl << '{';
 
     return true;
 }
@@ -4298,6 +5060,7 @@ void
 Slice::Gen::AsyncImplVisitor::visitUnitEnd(const UnitPtr&)
 {
     H << sp << nl << '}';
+    H << nl << "/// \\endcond";
 }
 
 bool
@@ -4412,7 +5175,9 @@ Slice::Gen::AsyncImplVisitor::visitOperation(const OperationPtr& p)
     H << nl << "virtual void ice_response(" << params << ");";
     H << eb << ';';
 
-    C << sp << nl << "IceAsync" << classScopedAMD << '_' << name << "::" << classNameAMD << '_' << name
+    C << sp;
+    C << nl << "/// \\cond INTERNAL";
+    C << nl << "IceAsync" << classScopedAMD << '_' << name << "::" << classNameAMD << '_' << name
       << "(::IceInternal::Incoming& in) :";
     C.inc();
     C << nl << "::IceInternal::IncomingAsync(in)";
@@ -4439,6 +5204,7 @@ Slice::Gen::AsyncImplVisitor::visitOperation(const OperationPtr& p)
     }
     C << nl << "completed();";
     C << eb;
+    C << nl << "/// \\endcond";
 }
 
 Slice::Gen::StreamVisitor::StreamVisitor(Output& h, Output& c, const string& dllExport) :
@@ -4465,6 +5231,7 @@ Slice::Gen::StreamVisitor::visitModuleStart(const ModulePtr& m)
         // Only emit this for the top-level module.
         //
         H << sp;
+        H << nl << "/// \\cond STREAM";
         H << nl << "namespace Ice" << nl << '{' << sp;
 
         C << sp;
@@ -4483,6 +5250,7 @@ Slice::Gen::StreamVisitor::visitModuleEnd(const ModulePtr& m)
         // Only emit this for the top-level module.
         //
         H << nl << '}';
+        H << nl << "/// \\endcond";
         C << nl << '}';
     }
 }
@@ -4607,6 +5375,7 @@ Slice::Gen::MetaDataVisitor::visitUnitStart(const UnitPtr& p)
                 static const string cppHeaderExtPrefix = "cpp:header-ext:";
                 static const string cppSourceExtPrefix = "cpp:source-ext:";
                 static const string cppDllExportPrefix = "cpp:dll-export:";
+                static const string cppDoxygenIncludePrefix = "cpp:doxygen:include:";
 
                 if(s.find(cppIncludePrefix) == 0 && s.size() > cppIncludePrefix.size())
                 {
@@ -4652,6 +5421,10 @@ Slice::Gen::MetaDataVisitor::visitUnitStart(const UnitPtr& p)
                     }
                     continue;
                 }
+                else if(s.find(cppDoxygenIncludePrefix) == 0 && s.size() > cppDoxygenIncludePrefix.size())
+                {
+                    continue;
+                }
 
                 ostringstream ostr;
                 ostr << "ignoring invalid global metadata `" << s << "'";
@@ -5308,7 +6081,8 @@ Slice::Gen::Cpp11DeclVisitor::visitClassDefStart(const ClassDefPtr& p)
         if(p->compactId() >= 0)
         {
             string n = "iceC" + p->flattenedScope() + p->name() + "_compactIdInit ";
-            C << "const ::IceInternal::CompactIdInit " << n << "(\"" << p->scoped() << "\", " << p->compactId() << ");";
+            C << "const ::IceInternal::CompactIdInit " << n << "(\"" << p->scoped() << "\", " << p->compactId()
+              << ");";
         }
     }
 
@@ -5444,9 +6218,12 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     DataMemberList baseDataMembers;
 
     vector<string> params;
-    vector<string> allTypes;
     vector<string> allParamDecls;
     vector<string> baseParams;
+    map<string, CommentPtr> allComments;
+
+    string fileParam = "file";
+    string lineParam = "line";
 
     for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
     {
@@ -5457,8 +6234,22 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     {
         string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(),
                                             _useWstring | TypeContextCpp11);
-        allTypes.push_back(typeName);
-        allParamDecls.push_back(typeName + " iceP_" + (*q)->name());
+        allParamDecls.push_back(typeName + " " + fixKwd((*q)->name()));
+
+        CommentPtr comment = (*q)->parseComment(false);
+        if(comment)
+        {
+            allComments[(*q)->name()] = comment;
+        }
+
+        if((*q)->name() == "file")
+        {
+            fileParam = "file_";
+        }
+        else if((*q)->name() == "line")
+        {
+            fileParam = "line_";
+        }
     }
 
     if(base)
@@ -5466,18 +6257,20 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
         baseDataMembers = base->allDataMembers();
         for(DataMemberList::const_iterator q = baseDataMembers.begin(); q != baseDataMembers.end(); ++q)
         {
-            baseParams.push_back("iceP_" + (*q)->name());
+            baseParams.push_back(fixKwd((*q)->name()));
         }
     }
 
-    string helperClass = getAbsolute(p->isLocal() ? "::Ice::LocalExceptionHelper" : "::Ice::UserExceptionHelper", scope);
+    string helperClass =
+        getAbsolute(p->isLocal() ? "::Ice::LocalExceptionHelper" : "::Ice::UserExceptionHelper", scope);
     string baseClass = base ?
         getAbsolute(fixKwd(base->scoped()), scope) :
         getAbsolute(p->isLocal() ? "::Ice::LocalException" : "::Ice::UserException", scope);
     string templateParameters = name + ", " + baseClass;
 
-    H << sp << nl;
-    H << "class " << _dllClassExport << name << " : public " << helperClass << "<" << templateParameters << ">";
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllClassExport << name << " : public " << helperClass << "<" << templateParameters << ">";
     H << sb;
 
     H.dec();
@@ -5497,9 +6290,17 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
 
     if(p->isLocal())
     {
-        H << sp << nl << name << "(const char* file_, int line_) : ";
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * The file and line number are required for all local exceptions.";
+        H << nl << " * @param " << fileParam
+          << " The file name in which the exception was raised, typically __FILE__.";
+        H << nl << " * @param " << lineParam
+          << " The line number at which the exception was raised, typically __LINE__.";
+        H << nl << " */";
+        H << nl << name << "(const char* " << fileParam << ", int " << lineParam << ") : ";
         H << getAbsolute("::Ice::LocalExceptionHelper", scope) << "<" << templateParameters << ">";
-        H << "(file_, line_)";
+        H << "(" << fileParam << ", " << lineParam << ")";
         H << sb;
         H << eb;
     }
@@ -5510,10 +6311,30 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
 
     if(!allDataMembers.empty())
     {
-        H << sp << nl << name << "(";
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * One-shot constructor to initialize all data members.";
+        if(p->isLocal())
+        {
+            H << nl << " * The file and line number are required for all local exceptions.";
+            H << nl << " * @param " << fileParam
+              << " The file name in which the exception was raised, typically __FILE__.";
+            H << nl << " * @param " << lineParam
+              << " The line number at which the exception was raised, typically __LINE__.";
+        }
+        for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
+        {
+            map<string, CommentPtr>::iterator r = allComments.find((*q)->name());
+            if(r != allComments.end())
+            {
+                H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview());
+            }
+        }
+        H << nl << " */";
+        H << nl << name << "(";
         if(p->isLocal())
         {
-            H << "const char* file_, int line_";
+            H << "const char* " << fileParam << ", int " << lineParam;
             if(!allParamDecls.empty())
             {
                 H << ", ";
@@ -5535,7 +6356,7 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
             H << nl << helperClass << "<" << templateParameters << ">" << "(";
             if(p->isLocal())
             {
-                H << "file_, line_";
+                H << fileParam << ", " << lineParam;
                 if(!baseDataMembers.empty())
                 {
                     H << ", ";
@@ -5550,11 +6371,11 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
                 }
                 if(isMovable((*q)->type()))
                 {
-                    H << "::std::move(iceP_" << (*q)->name() << ")";
+                    H << "::std::move(" << fixKwd((*q)->name()) << ")";
                 }
                 else
                 {
-                    H << "iceP_" << (*q)->name();
+                    H << fixKwd((*q)->name());
                 }
             }
 
@@ -5567,7 +6388,7 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
         else if(p->isLocal())
         {
             H << " " << getAbsolute("::Ice::LocalExceptionHelper", scope) << "<" << templateParameters << ">";
-            H << "(file_, line_)";
+            H << "(" << fileParam << ", " << lineParam << ")";
             if(!dataMembers.empty())
             {
                 H << ",";
@@ -5576,17 +6397,18 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
 
         for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
         {
+            string memberName = fixKwd((*q)->name());
             if(q != dataMembers.begin())
             {
                 H << ",";
             }
             if(isMovable((*q)->type()))
             {
-                H << nl << fixKwd((*q)->name()) << "(::std::move(iceP_" << (*q)->name() << "))";
+                H << nl << memberName << "(::std::move(" << memberName << "))";
             }
             else
             {
-                H << nl << fixKwd((*q)->name()) << "(iceP_" << (*q)->name() << ")";
+                H << nl << memberName << "(" << memberName << ")";
             }
         }
 
@@ -5595,9 +6417,18 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
         H << eb;
     }
 
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains a tuple containing all of the exception's data members.";
+    H << nl << " * @return The data members in a tuple.";
+    H << nl << " */";
     writeIceTuple(H, scope, p->allDataMembers(), _useWstring);
 
     H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID of this exception.";
+    H << nl << " * @return The fully-scoped type ID.";
+    H << nl << " */";
     H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
 
     C << sp << nl << "const ::std::string&" << nl << scoped.substr(2) << "::ice_staticId()";
@@ -5612,20 +6443,30 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
     StringList metaData = p->getMetaData();
     if(find(metaData.begin(), metaData.end(), "cpp:ice_print") != metaData.end())
     {
-        H << nl << _dllMemberExport << "virtual void ice_print(::std::ostream&) const override;";
+        H << nl << "/**";
+        H << nl << " * Prints this exception to the given stream.";
+        H << nl << " * @param stream The target stream.";
+        H << nl << " */";
+        H << nl << _dllMemberExport << "virtual void ice_print(::std::ostream& stream) const override;";
     }
 
     if(!p->isLocal() && p->usesClasses(false))
     {
         if(!base || (base && !base->usesClasses(false)))
         {
-            H << sp << nl << _dllMemberExport << "virtual bool _usesClasses() const override;";
+            H << sp;
+            H << nl << "/// \\cond STREAM";
+            H << nl << _dllMemberExport << "virtual bool _usesClasses() const override;";
+            H << nl << "/// \\endcond";
 
-            C << sp << nl << "bool";
+            C << sp;
+            C << nl << "/// \\cond STREAM";
+            C << nl << "bool";
             C << nl << scoped.substr(2) << "::_usesClasses() const";
             C << sb;
             C << nl << "return true;";
             C << eb;
+            C << nl << "/// \\endcond";
         }
     }
 
@@ -5653,23 +6494,34 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         if(preserved && !basePreserved)
         {
             H << sp;
+            H << nl << "/**";
+            H << nl << " * Obtains the SlicedData object created when an unknown exception type was marshaled";
+            H << nl << " * in the sliced format and the Ice run time sliced it to a known type.";
+            H << nl << " * @return The SlicedData object, or nil if the exception was not sliced or was not";
+            H << nl << " * marshaled in the sliced format.";
+            H << nl << " */";
             H << nl << _dllMemberExport << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope)
               << "> ice_getSlicedData() const override;";
             H << sp;
+            H << nl << "/// \\cond STREAM";
             H << nl << _dllMemberExport << "virtual void _write(" << getAbsolute("::Ice::OutputStream*", scope)
               << ") const override;";
             H << nl << _dllMemberExport << "virtual void _read(" << getAbsolute("::Ice::InputStream*", scope)
               << ") override;";
 
             H << sp << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _slicedData;";
+            H << nl << "/// \\endcond";
 
             C << sp;
-            C << nl << "::std::shared_ptr<::Ice::SlicedData>" << nl << scoped.substr(2) << "::ice_getSlicedData() const";
+            C << nl << "::std::shared_ptr<::Ice::SlicedData>" << nl << scoped.substr(2)
+              << "::ice_getSlicedData() const";
             C << sb;
             C << nl << "return _slicedData;";
             C << eb;
 
-            C << sp << nl << "void" << nl << scoped.substr(2) << "::_write("
+            C << sp;
+            C << nl << "/// \\cond STREAM";
+            C << nl << "void" << nl << scoped.substr(2) << "::_write("
               << getAbsolute("::Ice::OutputStream*", scope) << " ostr) const";
             C << sb;
             C << nl << "ostr->startException(_slicedData);";
@@ -5677,13 +6529,14 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
             C << nl << "ostr->endException();";
             C << eb;
 
-            C << sp << nl << "void" << nl << scoped.substr(2) << "::_read(" << getAbsolute("::Ice::InputStream*", scope)
-              << " istr)";
+            C << sp << nl << "void" << nl << scoped.substr(2) << "::_read("
+              << getAbsolute("::Ice::InputStream*", scope) << " istr)";
             C << sb;
             C << nl << "istr->startException();";
             C << nl << "_readImpl(istr);";
             C << nl << "_slicedData = istr->endException(true);";
             C << eb;
+            C << nl << "/// \\endcond";
         }
     }
     H << eb << ';';
@@ -5698,7 +6551,10 @@ Slice::Gen::Cpp11TypesVisitor::visitExceptionEnd(const ExceptionPtr& p)
         if(!_doneStaticSymbol)
         {
             _doneStaticSymbol = true;
-            H << sp << nl << "static " << name << " _iceS_" << p->name() << "_init;";
+            H << sp;
+            H << nl << "/// \\cond INTERNAL";
+            H << nl << "static " << name << " _iceS_" << p->name() << "_init;";
+            H << nl << "/// \\endcond";
         }
     }
 
@@ -5710,7 +6566,9 @@ Slice::Gen::Cpp11TypesVisitor::visitStructStart(const StructPtr& p)
 {
     _useWstring = setUseWstring(p, _useWstringHist, _useWstring);
 
-    H << sp << nl << "struct " << fixKwd(p->name());
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "struct " << fixKwd(p->name());
     H << sb;
 
     return true;
@@ -5719,6 +6577,11 @@ Slice::Gen::Cpp11TypesVisitor::visitStructStart(const StructPtr& p)
 void
 Slice::Gen::Cpp11TypesVisitor::visitStructEnd(const StructPtr& p)
 {
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains a tuple containing all of the exception's data members.";
+    H << nl << " * @return The data members in a tuple.";
+    H << nl << " */";
     writeIceTuple(H, fixKwd(p->scope()), p->dataMembers(), _useWstring);
     H << eb << ';';
     _useWstring = resetUseWstring(_useWstringHist);
@@ -5729,6 +6592,7 @@ Slice::Gen::Cpp11TypesVisitor::visitDataMember(const DataMemberPtr& p)
 {
     string scope = fixKwd(ContainedPtr::dynamicCast(p->container())->scope());
     string name = fixKwd(p->name());
+    writeDocSummary(H, p);
     H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), _useWstring | TypeContextCpp11)
       << ' ' << name;
 
@@ -5769,6 +6633,7 @@ Slice::Gen::Cpp11TypesVisitor::visitSequence(const SequencePtr& p)
 
     string seqType = findMetaData(metaData, _useWstring);
     H << sp;
+    writeDocSummary(H, p);
 
     if(!seqType.empty())
     {
@@ -5787,6 +6652,10 @@ Slice::Gen::Cpp11TypesVisitor::visitDictionary(const DictionaryPtr& p)
     string scope = fixKwd(p->scope());
     string dictType = findMetaData(p->getMetaData());
     int typeCtx = p->isLocal() ? (_useWstring | TypeContextLocal) : _useWstring;
+
+    H << sp;
+    writeDocSummary(H, p);
+
     if(dictType.empty())
     {
         //
@@ -5797,14 +6666,14 @@ Slice::Gen::Cpp11TypesVisitor::visitDictionary(const DictionaryPtr& p)
         string ks = typeToString(keyType, scope, p->keyMetaData(), typeCtx | TypeContextCpp11);
         string vs = typeToString(valueType, scope, p->valueMetaData(), typeCtx | TypeContextCpp11);
 
-        H << sp << nl << "using " << name << " = ::std::map<" << ks << ", " << vs << ">;";
+        H << nl << "using " << name << " = ::std::map<" << ks << ", " << vs << ">;";
     }
     else
     {
         //
         // A custom dictionary
         //
-        H << sp << nl << "using " << name << " = " << dictType << ';';
+        H << nl << "using " << name << " = " << dictType << ';';
     }
 }
 
@@ -5869,7 +6738,9 @@ Slice::Gen::Cpp11ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
         base = bases.front();
     }
 
-    H << sp << nl << "class " << _dllClassExport << p->name() << "Prx : public virtual "
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllClassExport << p->name() << "Prx : public virtual "
       << getAbsolute("::Ice::Proxy", scope) << "<" << fixKwd(p->name() + "Prx") << ", ";
     if(bases.empty() || (base && base->allOperations().empty()))
     {
@@ -5904,25 +6775,35 @@ Slice::Gen::Cpp11ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
     const string scoped = fixKwd(p->scoped() + "Prx");
     const string scope = fixKwd(p->scope());
 
-    H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID of this " << (p->isInterface() ? "interface" : "class") << ".";
+    H << nl << " * @return The fully-scoped type ID.";
+    H << nl << " */";
+    H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
 
     H.dec();
     H << sp << nl << "protected:";
     H.inc();
-    H << sp << nl << getAbsolute(prx, scope) << "() = default;";
+    H << sp;
+    H << nl << "/// \\cond INTERNAL";
+    H << nl << getAbsolute(prx, scope) << "() = default;";
     H << nl << "friend ::std::shared_ptr<" << getAbsolute(prx, scope) << "> IceInternal::createProxy<"
       << getAbsolute(prx, scope) << ">();";
     H << sp;
     H << nl << _dllMemberExport << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::ObjectPrx", scope)
       << "> _newInstance() const override;";
+    H << nl << "/// \\endcond";
     H << eb << ';';
 
     C << sp;
+    C << nl << "/// \\cond INTERNAL";
     C << nl << "::std::shared_ptr<::Ice::ObjectPrx>";
     C << nl << scoped.substr(2) << "::_newInstance() const";
     C << sb;
     C << nl << "return ::IceInternal::createProxy<" << getAbsolute(prx, scope) << ">();";
     C << eb;
+    C << nl << "/// \\endcond";
     C << sp;
     C << nl << "const ::std::string&" << nl << scoped.substr(2) << "::ice_staticId()";
     C << sb;
@@ -5952,20 +6833,22 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
 
     vector<string> inParamsS;
     vector<string> inParamsDecl;
+    vector<string> inParamsImplDecl;
 
     vector<string> futureOutParams;
     vector<string> lambdaOutParams;
 
     ParamDeclList paramList = p->parameters();
-    ParamDeclList inParams;
-    ParamDeclList outParams;
+    ParamDeclList inParams = p->inParameters();
+    ParamDeclList outParams = p->outParameters();
 
     string returnValueS = "returnValue";
     bool outParamsHasOpt = false;
 
     if(ret)
     {
-        futureOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring | TypeContextCpp11));
+        futureOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring |
+                                               TypeContextCpp11));
 
         lambdaOutParams.push_back(typeToString(ret, retIsOpt, clScope, p->getMetaData(), _useWstring |
                                                TypeContextInParam | TypeContextCpp11));
@@ -5975,7 +6858,7 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
 
     for(ParamDeclList::const_iterator q = paramList.begin(); q != paramList.end(); ++q)
     {
-        string paramName = fixKwd(paramPrefix + (*q)->name());
+        string paramName = fixKwd((*q)->name());
         StringList metaData = (*q)->getMetaData();
 
         if((*q)->isOutParam())
@@ -5992,7 +6875,6 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
             paramsDecl.push_back(outputTypeString + ' ' + paramName);
 
             outParamsHasOpt |= (*q)->optional();
-            outParams.push_back(*q);
 
             if((*q)->name() == "returnValue")
             {
@@ -6009,12 +6891,16 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
 
             inParamsS.push_back(typeString);
             inParamsDecl.push_back(typeString + ' ' + paramName);
-            inParams.push_back(*q);
+            inParamsImplDecl.push_back(typeString + ' ' + paramPrefix + (*q)->name());
         }
     }
 
     string scoped = fixKwd(cl->scope() + cl->name() + "Prx" + "::").substr(2);
 
+    const string contextParam = escapeParam(paramList, "context");
+    const string contextDecl = "const " + getAbsolute("::Ice::Context&", clScope) + " " + contextParam + " = " +
+        getAbsolute("::Ice::noExplicitContext", clScope);
+
     string futureT;
     if(futureOutParams.empty())
     {
@@ -6029,14 +6915,23 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
         futureT = resultStructName(name, fixKwd(cl->name()));
     }
 
-    string deprecateSymbol = getDeprecateSymbol(p, cl);
+    const string deprecateSymbol = getDeprecateSymbol(p, cl);
+
+    CommentPtr comment = p->parseComment(false);
+    const string contextDoc = "@param " + contextParam + " The Context map to send with the invocation.";
+    const string futureDoc = "The future object for the invocation.";
 
     //
     // Synchronous operation
     //
-    H << sp << nl << deprecateSymbol << retS << ' ' << fixKwd(name) << spar << paramsDecl;
-    H << ("const " + getAbsolute("::Ice::Context&", clScope) + " context = "
-          + getAbsolute("Ice::noExplicitContext", clScope.substr(2))) << epar;
+    H << sp;
+    if(comment)
+    {
+        StringList postParams;
+        postParams.push_back(contextDoc);
+        writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), postParams, comment->returns());
+    }
+    H << nl << deprecateSymbol << retS << ' ' << fixKwd(name) << spar << paramsDecl << contextDecl << epar;
     H << sb;
     H << nl;
     if(futureOutParams.size() == 1)
@@ -6047,12 +6942,12 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
         }
         else
         {
-            H << paramPrefix << (*outParams.begin())->name() << " = ";
+            H << fixKwd((*outParams.begin())->name()) << " = ";
         }
     }
     else if(futureOutParams.size() > 1)
     {
-        H << "auto result = ";
+        H << "auto _result = ";
     }
 
     H << "_makePromiseOutgoing<" << getAbsolute(futureT, cl->scoped()) << ">";
@@ -6060,19 +6955,19 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
     H << spar << "true, this" << "&" + cl->name() + "Prx::_iceI_" + name;
     for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q)
     {
-        H << fixKwd(paramPrefix + (*q)->name());
+        H << fixKwd((*q)->name());
     }
-    H << "context" << epar << ".get();";
+    H << contextParam << epar << ".get();";
     if(futureOutParams.size() > 1)
     {
         for(ParamDeclList::const_iterator q = outParams.begin(); q != outParams.end(); ++q)
         {
-            H << nl << paramPrefix << (*q)->name() << " = ";
-            H << condMove(isMovable((*q)->type()), "result." + fixKwd((*q)->name())) + ";";
+            H << nl << fixKwd((*q)->name()) << " = ";
+            H << condMove(isMovable((*q)->type()), "_result." + fixKwd((*q)->name())) + ";";
         }
         if(ret)
         {
-            H << nl << "return " + condMove(isMovable(ret), "result." + returnValueS) + ";";
+            H << nl << "return " + condMove(isMovable(ret), "_result." + returnValueS) + ";";
         }
     }
     H << eb;
@@ -6081,10 +6976,15 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
     // Promise based asynchronous operation
     //
     H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back(contextDoc);
+        returns.push_back(futureDoc);
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
     H << nl << "template<template<typename> class P = ::std::promise>";
-    H << nl << deprecateSymbol << "auto " << name << "Async" << spar << inParamsDecl;
-    H << ("const " + getAbsolute("::Ice::Context&", clScope) + " context = "
-          + getAbsolute("::Ice::noExplicitContext", clScope)) << epar;
+    H << nl << deprecateSymbol << "auto " << name << "Async" << spar << inParamsDecl << contextDecl << epar;
     H.inc();
     H << nl << "-> decltype(::std::declval<P<" << futureT << ">>().get_future())";
     H.dec();
@@ -6095,9 +6995,9 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
     H << "false, this" << string("&" + cl->name() + "Prx::_iceI_" + name);
     for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q)
     {
-        H << fixKwd(paramPrefix + (*q)->name());
+        H << fixKwd((*q)->name());
     }
-    H << "context" << epar << ";";
+    H << contextParam << epar << ";";
     H << eb;
 
     //
@@ -6105,7 +7005,21 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
     //
     bool lambdaCustomOut = (lambdaOutParams != futureOutParams);
 
+    const string responseParam = escapeParam(inParams, "response");
+    const string exParam = escapeParam(inParams, "ex");
+    const string sentParam = escapeParam(inParams, "sent");
+
     H << sp;
+    if(comment)
+    {
+        StringList postParams, returns;
+        postParams.push_back("@param " + responseParam + " The response callback.");
+        postParams.push_back("@param " + exParam + " The exception callback.");
+        postParams.push_back("@param " + sentParam + " The sent callback.");
+        postParams.push_back(contextDoc);
+        returns.push_back("A function that can be called to cancel the invocation locally.");
+        writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+    }
     H << nl;
     if(lambdaCustomOut)
     {
@@ -6143,15 +7057,10 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
         H << nl;
     }
 
-    H << "::std::function<void" << spar << lambdaOutParams << epar << ">"
-        + string(!lambdaCustomOut ? " response": "") + ",";
-    H << nl << "::std::function<void(::std::exception_ptr)>"
-        + string(!lambdaCustomOut ? " ex" : "") + " = nullptr,";
-    H << nl << "::std::function<void(bool)>"
-        + string(!lambdaCustomOut ? " sent" : "") + " = nullptr,";
-    H << nl << "const " << getAbsolute("::Ice::Context&", clScope)
-        + string(!lambdaCustomOut ? " context" : "") + " = "
-        + getAbsolute("Ice::noExplicitContext", clScope.substr(2)) + ")" + string(lambdaCustomOut ? ";" : "");
+    H << "::std::function<void" << spar << lambdaOutParams << epar << "> " << responseParam << ",";
+    H << nl << "::std::function<void(::std::exception_ptr)> " << exParam << " = nullptr,";
+    H << nl << "::std::function<void(bool)> " << sentParam << " = nullptr,";
+    H << nl << contextDecl << ")" << string(lambdaCustomOut ? ";" : "");
 
     H.restoreIndent();
     if(lambdaCustomOut)
@@ -6164,11 +7073,11 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
         C << nl << "::std::function<void()>";
         C << nl << scoped << name << "Async(";
         C.useCurrentPosAsIndent();
-        if(!inParamsDecl.empty())
+        if(!inParamsImplDecl.empty())
         {
-            for(vector<string>::const_iterator q = inParamsDecl.begin(); q != inParamsDecl.end(); ++q)
+            for(vector<string>::const_iterator q = inParamsImplDecl.begin(); q != inParamsImplDecl.end(); ++q)
             {
-                if(q != inParamsDecl.begin())
+                if(q != inParamsImplDecl.begin())
                 {
                     C << " ";
                 }
@@ -6246,30 +7155,30 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
         H << sb;
         if(futureOutParams.size() > 1)
         {
-            H << nl << "auto responseCb = [response](" << futureT << "&& result)";
+            H << nl << "auto _responseCb = [response](" << futureT << "&& _result)";
             H << sb;
-            H << nl << "response" << spar;
+            H << nl << responseParam << spar;
 
             if(ret)
             {
-                H << condMove(isMovable(ret), string("result.") + returnValueS);
+                H << condMove(isMovable(ret), string("_result.") + returnValueS);
             }
             for(ParamDeclList::const_iterator q = outParams.begin(); q != outParams.end(); ++q)
             {
-                H << condMove(isMovable((*q)->type()), "result." + fixKwd((*q)->name()));
+                H << condMove(isMovable((*q)->type()), "_result." + fixKwd((*q)->name()));
             }
             H << epar << ";" << eb << ";";
         }
 
         H << nl << "return _makeLamdaOutgoing<" << futureT << ">" << spar;
 
-        H << (futureOutParams.size() > 1 ? "responseCb" : "response") << "ex" << "sent" << "this";
+        H << (futureOutParams.size() > 1 ? "_responseCb" : responseParam) << exParam << sentParam << "this";
         H << string("&" + getAbsolute(scoped, clScope.substr(2)) + "_iceI_" + name);
         for(ParamDeclList::const_iterator q = inParams.begin(); q != inParams.end(); ++q)
         {
-            H << fixKwd(paramPrefix + (*q)->name());
+            H << fixKwd((*q)->name());
         }
-        H << "context" << epar << ";";
+        H << contextParam << epar << ";";
         H << eb;
     }
 
@@ -6278,16 +7187,19 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
     //
 
     H << sp;
+    H << nl << "/// \\cond INTERNAL";
     H << nl << _dllMemberExport << "void _iceI_" << name << spar;
     H << "const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<" + futureT + ">>&";
     H << inParamsS;
     H << ("const " + getAbsolute("::Ice::Context&", clScope));
     H << epar << ";";
+    H << nl << "/// \\endcond";
 
     C << sp;
+    C << nl << "/// \\cond INTERNAL";
     C << nl << "void" << nl << scoped << "_iceI_" << name << spar;
     C << "const ::std::shared_ptr<::IceInternal::OutgoingAsyncT<" + futureT + ">>& outAsync";
-    C << inParamsDecl << ("const " + getAbsolute("::Ice::Context&", clScope) + " context");
+    C << inParamsImplDecl << ("const " + getAbsolute("::Ice::Context&", clScope) + " context");
     C << epar;
     C << sb;
     if(p->returnsData())
@@ -6354,13 +7266,16 @@ Slice::Gen::Cpp11ProxyVisitor::visitOperation(const OperationPtr& p)
 
     C.dec();
     C << ");" << eb;
+    C << nl << "/// \\endcond";
 }
 
 void
 Slice::Gen::Cpp11TypesVisitor::visitEnum(const EnumPtr& p)
 {
     bool unscoped = findMetaData(p->getMetaData(), TypeContextCpp11) == "%unscoped";
-    H << sp << nl << "enum ";
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "enum ";
     if(!unscoped)
     {
         H << "class ";
@@ -6379,6 +7294,7 @@ Slice::Gen::Cpp11TypesVisitor::visitEnum(const EnumPtr& p)
     const bool explicitValue = p->explicitValue();
     for(EnumeratorList::const_iterator en = enumerators.begin(); en != enumerators.end();)
     {
+        writeDocSummary(H, *en);
         H << nl << fixKwd((*en)->name());
         //
         // If any of the enumerators were assigned an explicit value, we emit
@@ -6401,6 +7317,7 @@ Slice::Gen::Cpp11TypesVisitor::visitConst(const ConstPtr& p)
 {
     const string scope = fixKwd(p->scope());
     H << sp;
+    writeDocSummary(H, p);
     H << nl << (isConstexprType(p->type()) ? "constexpr " : "const ")
       << typeToString(p->type(), scope, p->typeMetaData(), _useWstring | TypeContextCpp11) << " " << fixKwd(p->name())
       << " = ";
@@ -6409,7 +7326,8 @@ Slice::Gen::Cpp11TypesVisitor::visitConst(const ConstPtr& p)
 }
 
 void
-Slice::Gen::Cpp11TypesVisitor::emitUpcall(const ExceptionPtr& base, const string& call, const string& scope, bool isLocal)
+Slice::Gen::Cpp11TypesVisitor::emitUpcall(const ExceptionPtr& base, const string& call, const string& scope,
+                                          bool isLocal)
 {
     C << nl;
     if(base)
@@ -6448,6 +7366,7 @@ Slice::Gen::Cpp11ObjectVisitor::emitDataMember(const DataMemberPtr& p)
         typeContext |= TypeContextLocal;
     }
 
+    writeDocSummary(H, p);
     H << nl << typeToString(p->type(), p->optional(), scope, p->getMetaData(), typeContext) << ' ' << name;
 
     string defaultValue = p->defaultValue();
@@ -6547,11 +7466,18 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     {
         int typeCtx = _useWstring | TypeContextLocal | TypeContextCpp11;
 
-        // Generate alias
-        H << sp << nl << "using " << name << " = ";
-
         // A delegate only has one operation
         OperationPtr op = p->allOperations().front();
+
+        // Generate alias
+        H << sp;
+        CommentPtr comment = op->parseComment(false);
+        if(comment)
+        {
+            writeOpDocSummary(H, op, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns());
+        }
+        H << nl << "using " << name << " = ";
+
         TypePtr ret = op->returnType();
         string retS = returnTypeToString(ret, op->returnIsOptional(), scope, op->getMetaData(), typeCtx);
 
@@ -6568,6 +7494,7 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
             {
                 H << inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeCtx);
             }
+            H << " " << fixKwd((*q)->name());
             H << (IceUtilInternal::distance(q, paramList.end()) == 1  ? "" : ", ");
         }
         H << ")>;";
@@ -6585,7 +7512,9 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     DataMemberList dataMembers = p->dataMembers();
     DataMemberList allDataMembers = p->allDataMembers();
 
-    H << sp << nl << "class " << _dllClassExport << name;
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllClassExport << name;
     H.useCurrentPosAsIndent();
     if(!bases.empty())
     {
@@ -6622,22 +7551,6 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitClassDefStart(const ClassDefPtr& p)
     C << sb;
     C << eb;
 
-    vector<string> params;
-    vector<string> allTypes;
-    vector<string> allParamDecls;
-
-    for(DataMemberList::const_iterator q = dataMembers.begin(); q != dataMembers.end(); ++q)
-    {
-        params.push_back(fixKwd((*q)->name()));
-    }
-
-    for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
-    {
-        string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), _useWstring | TypeContextLocal);
-        allTypes.push_back(typeName);
-        allParamDecls.push_back(typeName + " iceP_" + (*q)->name());
-    }
-
     if(!p->isInterface())
     {
         if(p->hasDefaultValues())
@@ -6748,87 +7661,42 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p)
 
     int typeCtx = _useWstring | TypeContextLocal | TypeContextCpp11;
     TypePtr ret = p->returnType();
-    string retS = returnTypeToString(ret, p->returnIsOptional(), scope, p->getMetaData(),
-                                     typeCtx);
+    string retS = returnTypeToString(ret, p->returnIsOptional(), scope, p->getMetaData(), typeCtx);
 
     string params = "(";
-    string paramsDecl = "(";
-    string args = "(";
 
     ContainerPtr container = p->container();
     ClassDefPtr cl = ClassDefPtr::dynamicCast(container);
     string classScope = fixKwd(cl->scope());
 
-    ParamDeclList inParams;
-    ParamDeclList outParams;
-    ParamDeclList paramList = p->parameters();
-    vector< string> outDecls;
-    for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q)
-    {
-        string paramName = fixKwd(string(paramPrefix) + (*q)->name());
-        TypePtr type = (*q)->type();
-        bool isOutParam = (*q)->isOutParam();
-        string typeString;
-        if(isOutParam)
-        {
-            outParams.push_back(*q);
-            typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx);
-        }
-        else
-        {
-            inParams.push_back(*q);
-            typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx);
-        }
-
-        if(q != paramList.begin())
-        {
-            params += ", ";
-            paramsDecl += ", ";
-            args += ", ";
-        }
-
-        params += typeString;
-        paramsDecl += typeString;
-        paramsDecl += ' ';
-        paramsDecl += paramName;
-        args += paramName;
-
-        if(isOutParam)
-        {
-            outDecls.push_back(typeString);
-        }
-    }
-
-    params += ')';
-    paramsDecl += ')';
-    args += ')';
-
     string isConst = ((p->mode() == Operation::Nonmutating) || p->hasMetaData("cpp:const")) ? " const" : "";
     string noExcept = p->hasMetaData("cpp:noexcept") ? " noexcept" : "";
 
     string deprecateSymbol = getDeprecateSymbol(p, cl);
 
+    CommentPtr comment = p->parseComment(false);
+
     if(cl->hasMetaData("async-oneway") || p->hasMetaData("async-oneway"))
     {
         vector<string> paramsDeclAMI;
         vector<string> outParamsDeclAMI;
         vector<string> paramsArgAMI;
-        ParamDeclList paramList = p->parameters();
+        ParamDeclList paramList = p->inParameters();
         for(ParamDeclList::const_iterator r = paramList.begin(); r != paramList.end(); ++r)
         {
             string paramName = fixKwd((*r)->name());
 
             StringList metaData = (*r)->getMetaData();
-            string typeString;
-            if(!(*r)->isOutParam())
-            {
-                typeString = inputTypeToString((*r)->type(), (*r)->optional(), classScope, metaData, typeCtx);
-                paramsDeclAMI.push_back(typeString + ' ' + paramName);
-                paramsArgAMI.push_back(paramName);
-            }
+            string typeString = inputTypeToString((*r)->type(), (*r)->optional(), classScope, metaData, typeCtx);
+            paramsDeclAMI.push_back(typeString + ' ' + paramName);
+            paramsArgAMI.push_back(paramName);
         }
 
         H << sp;
+        if(comment)
+        {
+            writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns());
+        }
         H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << spar << paramsDeclAMI << epar
                 << isConst << noExcept;
         H << sb;
@@ -6836,11 +7704,25 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p)
         H << eb;
 
         H << sp;
+        if(comment)
+        {
+            string exParam = escapeParam(paramList, "exception");
+            string sentParam = escapeParam(paramList, "sent");
+            StringList postParams, returns;
+            postParams.push_back("@param " + exParam + " The exception callback.");
+            postParams.push_back("@param " + sentParam + " The sent callback.");
+            returns.push_back("A function that can be called to cancel the invocation locally.");
+            writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), postParams, returns);
+        }
         H << nl << "virtual ::std::function<void()>";
         H << nl << name << "Async(";
         H.useCurrentPosAsIndent();
         for(vector<string>::const_iterator i = paramsDeclAMI.begin(); i != paramsDeclAMI.end(); ++i)
         {
+            if(i != paramsDeclAMI.begin())
+            {
+                H << nl;
+            }
             H << *i << ",";
         }
         if(!paramsDeclAMI.empty())
@@ -6852,6 +7734,12 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p)
         H.restoreIndent();
 
         H << sp;
+        if(comment)
+        {
+            StringList returns;
+            returns.push_back("The future object for the invocation.");
+            writeOpDocSummary(H, p, comment, OpDocInParams, false, StringList(), StringList(), returns);
+        }
         H << nl << "template<template<typename> class P = ::std::promise>";
         H << nl << deprecateSymbol << "auto " << name << "Async" << spar << paramsDeclAMI << epar;
         H.inc();
@@ -6865,6 +7753,10 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p)
         H.useCurrentPosAsIndent();
         for(vector<string>::const_iterator i = paramsArgAMI.begin(); i != paramsArgAMI.end(); ++i)
         {
+            if(i != paramsArgAMI.begin())
+            {
+                H << " ";
+            }
             H << *i << ",";
         }
         if(!paramsArgAMI.empty())
@@ -6886,8 +7778,40 @@ Slice::Gen::Cpp11LocalObjectVisitor::visitOperation(const OperationPtr& p)
     }
     else
     {
+        ParamDeclList paramList = p->parameters();
+        for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q)
+        {
+            string paramName = fixKwd((*q)->name());
+            TypePtr type = (*q)->type();
+            string typeString;
+            if((*q)->isOutParam())
+            {
+                typeString = outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx);
+            }
+            else
+            {
+                typeString = inputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx);
+            }
+
+            if(q != paramList.begin())
+            {
+                params += ", ";
+            }
+
+            params += typeString;
+            params += ' ';
+            params += paramName;
+        }
+
+        params += ')';
+
         H << sp;
-        H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept << " = 0;";
+        if(comment)
+        {
+            writeOpDocSummary(H, p, comment, OpDocAllParams, true, StringList(), StringList(), comment->returns());
+        }
+        H << nl << deprecateSymbol << "virtual " << retS << ' ' << fixKwd(name) << params << isConst << noExcept
+          << " = 0;";
     }
 }
 
@@ -6943,7 +7867,9 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p)
         base = bases.front();
     }
 
-    H << sp << nl << "class " << _dllExport << name << " : ";
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllExport << name << " : ";
     H.useCurrentPosAsIndent();
     if(bases.empty() || (base && base->allOperations().empty()))
     {
@@ -6996,13 +7922,37 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p)
     assert(scopedIter != ids.end());
 
     H << sp;
-    H << nl << "virtual bool ice_isA(::std::string, const " << getAbsolute("::Ice::Current&", scope)
-      << ") const override;";
+    H << nl << "/**";
+    H << nl << " * Determines whether this object supports an interface with the given Slice type ID.";
+    H << nl << " * @param id The fully-scoped Slice type ID.";
+    H << nl << " * @param current The Current object for the invocation.";
+    H << nl << " * @return True if this object supports the interface, false, otherwise.";
+    H << nl << " */";
+    H << nl << "virtual bool ice_isA(::std::string id, const " << getAbsolute("::Ice::Current&", scope)
+      << " current) const override;";
+        H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains a list of the Slice type IDs representing the interfaces supported by this object.";
+    H << nl << " * @param current The Current object for the invocation.";
+    H << nl << " * @return A list of fully-scoped type IDs.";
+    H << nl << " */";
     H << nl
       << "virtual ::std::vector<::std::string> ice_ids(const " << getAbsolute("::Ice::Current&", scope)
-      << ") const override;";
-    H << nl << "virtual ::std::string ice_id(const " << getAbsolute("::Ice::Current&", scope) << ") const override;";
-    H << sp << nl << "static const ::std::string& ice_staticId();";
+      << " current) const override;";
+        H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains a Slice type ID representing the most-derived interface supported by this object.";
+    H << nl << " * @param current The Current object for the invocation.";
+    H << nl << " * @return A fully-scoped type ID.";
+    H << nl << " */";
+    H << nl << "virtual ::std::string ice_id(const " << getAbsolute("::Ice::Current&", scope)
+      << " current) const override;";
+        H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID corresponding to this class.";
+    H << nl << " * @return A fully-scoped type ID.";
+    H << nl << " */";
+    H << nl << "static const ::std::string& ice_staticId();";
 
     string flatName = "iceC" + p->flattenedScope() + p->name() + "_ids";
 
@@ -7017,7 +7967,8 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefStart(const ClassDefPtr& p)
     C << nl << "::std::vector<::std::string>" << nl << scoped.substr(2) << "::ice_ids(const "
       << getAbsolute("::Ice::Current&", scope) << ") const";
     C << sb;
-    C << nl << "return ::std::vector<::std::string>(&" << flatName << "[0], &" << flatName << '[' << ids.size() << "]);";
+    C << nl << "return ::std::vector<::std::string>(&" << flatName << "[0], &" << flatName << '[' << ids.size()
+      << "]);";
     C << eb;
 
     C << sp;
@@ -7069,17 +8020,21 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefEnd(const ClassDefPtr& p)
         string flatName = "iceC" + p->flattenedScope() + p->name() + "_ops";
 
         H << sp;
-        H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const " << getAbsolute("::Ice::Current&", scope)
-          << ") override;";
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "virtual bool _iceDispatch(::IceInternal::Incoming&, const "
+          << getAbsolute("::Ice::Current&", scope) << ") override;";
+        H << nl << "/// \\endcond";
 
         C << sp;
+        C << nl << "/// \\cond INTERNAL";
         C << nl << "bool";
         C << nl << scoped.substr(2) << "::_iceDispatch(::IceInternal::Incoming& in, const "
           << getAbsolute("::Ice::Current&", scope) << " current)";
         C << sb;
 
         C << nl << "::std::pair<const ::std::string*, const ::std::string*> r = "
-          << "::std::equal_range(" << flatName << ", " << flatName << " + " << allOpNames.size() << ", current.operation);";
+          << "::std::equal_range(" << flatName << ", " << flatName << " + " << allOpNames.size()
+          << ", current.operation);";
         C << nl << "if(r.first == r.second)";
         C << sb;
         C << nl << "throw " << getAbsolute("::Ice::OperationNotExistException", scope)
@@ -7104,6 +8059,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitClassDefEnd(const ClassDefPtr& p)
         C << eb;
         C << eb;
         C << eb;
+        C << nl << "/// \\endcond";
     }
 
     H << eb << ';';
@@ -7135,6 +8091,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
 
     vector<string> responseParams;
     vector<string> responseParamsDecl;
+    vector<string> responseParamsImplDecl;
 
     ContainerPtr container = p->container();
     ClassDefPtr cl = ClassDefPtr::dynamicCast(container);
@@ -7144,13 +8101,28 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
     string scope = fixKwd(cl->scope() + cl->name() + suffix + "::");
     string scoped = fixKwd(cl->scope() + cl->name() + suffix + "::" + p->name());
 
-    bool amd = (cl->hasMetaData("amd") || p->hasMetaData("amd"));
+    ParamDeclList inParams = p->inParameters();
+    ParamDeclList outParams = p->outParameters();
+    ParamDeclList paramList = p->parameters();
+
+    const bool amd = (cl->hasMetaData("amd") || p->hasMetaData("amd"));
+
+    const string returnValueParam = escapeParam(outParams, "returnValue");
+    const string responsecbParam = escapeParam(inParams, "response");
+    const string excbParam = escapeParam(inParams, "exception");
+    const string currentParam = escapeParam(amd ? inParams : paramList, "current");
+    const string currentTypeDecl = "const " + getAbsolute("::Ice::Current&", classScope);
+    const string currentDecl = currentTypeDecl + " " + currentParam;
+
+    CommentPtr comment = p->parseComment(false);
+
     if(ret)
     {
         string typeS = inputTypeToString(ret, p->returnIsOptional(), classScope, p->getMetaData(),
                                          _useWstring | TypeContextCpp11);
-        responseParams.push_back(typeS);
+        responseParams.push_back(typeS + " " + returnValueParam);
         responseParamsDecl.push_back(typeS + " ret");
+        responseParamsImplDecl.push_back(typeS + " ret");
     }
 
     string retS;
@@ -7168,36 +8140,35 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
                                   _useWstring | TypeContextCpp11);
     }
 
-    ParamDeclList inParams;
-    ParamDeclList outParams;
-    ParamDeclList paramList = p->parameters();
     for(ParamDeclList::iterator q = paramList.begin(); q != paramList.end(); ++q)
     {
         TypePtr type = (*q)->type();
-        string paramName = fixKwd(string(paramPrefix) + (*q)->name());
+        string paramName = fixKwd((*q)->name());
         bool isOutParam = (*q)->isOutParam();
         string typeString;
         int typeCtx = _useWstring | TypeContextCpp11;
+
         if(!isOutParam)
         {
-            inParams.push_back(*q);
             params.push_back(typeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(),
-                                          typeCtx | TypeContextInParam));
-            args.push_back(condMove(isMovable(type) && !isOutParam, paramName));
+                                          typeCtx | TypeContextInParam) + " " + paramName);
+            args.push_back(condMove(isMovable(type) && !isOutParam, paramPrefix + (*q)->name()));
         }
         else
         {
-            outParams.push_back(*q);
             if(!p->hasMarshaledResult() && !amd)
             {
-                params.push_back(outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx));
-                args.push_back(condMove(isMovable(type) && !isOutParam, paramName));
+                params.push_back(
+                    outputTypeToString(type, (*q)->optional(), classScope, (*q)->getMetaData(), typeCtx) + " " +
+                    paramName);
+                args.push_back(condMove(isMovable(type) && !isOutParam, paramPrefix + (*q)->name()));
             }
 
             string responseTypeS = inputTypeToString((*q)->type(), (*q)->optional(), classScope, (*q)->getMetaData(),
                                                      typeCtx);
-            responseParams.push_back(responseTypeS);
-            responseParamsDecl.push_back(responseTypeS + " " + paramName);
+            responseParams.push_back(responseTypeS + " " + paramName);
+            responseParamsDecl.push_back(responseTypeS + " " + paramPrefix + (*q)->name());
+            responseParamsImplDecl.push_back(responseTypeS + " " + paramPrefix + (*q)->name());
         }
     }
     if(amd)
@@ -7205,18 +8176,18 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
         if(p->hasMarshaledResult())
         {
             string resultName = resultStructName(name, "", true);
-            params.push_back("::std::function<void(const " + resultName + "&)>");
+            params.push_back("::std::function<void(const " + resultName + "&)> " + responsecbParam);
             args.push_back("inA->response<" + resultName + ">()");
         }
         else
         {
-            params.push_back("::std::function<void(" + joinString(responseParams, ",") + ")>");
+            params.push_back("::std::function<void(" + joinString(responseParams, ", ") + ")> " + responsecbParam);
             args.push_back(ret || !outParams.empty() ? "responseCB" : "inA->response()");
         }
-        params.push_back("::std::function<void(::std::exception_ptr)>");
+        params.push_back("::std::function<void(::std::exception_ptr)> " + excbParam);
         args.push_back("inA->exception()");
     }
-    params.push_back("const " + getAbsolute("::Ice::Current&", classScope));
+    params.push_back(currentDecl);
     args.push_back("current");
 
     if(cl->isInterface())
@@ -7228,18 +8199,41 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
     {
         string resultName = resultStructName(name, "", true);
         H << sp;
+        H << nl << "/**";
+        H << nl << " * Marshaled result structure for operation " << (amd ? name + "Async" : fixKwd(name)) << ".";
+        H << nl << " */";
         H << nl << "class " << resultName << " : public " << getAbsolute("::Ice::MarshaledResult", classScope);
         H << sb;
         H.dec();
         H << nl << "public:";
         H.inc();
-        H << nl << resultName << spar << responseParams << ("const " + getAbsolute("::Ice::Current&", classScope))
-          << epar << ";";
+        H << nl << "/**";
+        H << nl << " * Marshals the results immediately.";
+        if(ret && comment && !comment->returns().empty())
+        {
+            H << nl << " * @param " << returnValueParam << " " << getDocSentence(comment->returns());
+        }
+        map<string, StringList> paramComments;
+        if(comment)
+        {
+            paramComments = comment->parameters();
+        }
+        const string mrcurrent = escapeParam(outParams, "current");
+        for(ParamDeclList::iterator q = outParams.begin(); q != outParams.end(); ++q)
+        {
+            map<string, StringList>::iterator r = paramComments.find((*q)->name());
+            if(r != paramComments.end())
+            {
+                H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second);
+            }
+        }
+        H << nl << " * @param " << mrcurrent << " The Current object for the invocation.";
+        H << nl << " */";
+        H << nl << resultName << spar << responseParams << currentTypeDecl + " " + mrcurrent << epar << ";";
         H << eb << ';';
 
         C << sp << nl << scope.substr(2) << resultName << "::" << resultName;
-        C << spar << responseParamsDecl << ("const " + getAbsolute("::Ice::Current&", classScope) + " current")
-          << epar << ":";
+        C << spar << responseParamsImplDecl << currentTypeDecl + " current" << epar << ":";
         C.inc();
         C << nl << "MarshaledResult(current)";
         C.dec();
@@ -7260,17 +8254,41 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
     string deprecateSymbol = getDeprecateSymbol(p, cl);
 
     H << sp;
+    if(comment)
+    {
+        OpDocParamType pt = (amd || p->hasMarshaledResult()) ? OpDocInParams : OpDocAllParams;
+        StringList postParams, returns;
+        if(amd)
+        {
+            postParams.push_back("@param " + responsecbParam + " The response callback.");
+            postParams.push_back("@param " + excbParam + " The exception callback.");
+        }
+        else if(p->hasMarshaledResult())
+        {
+            returns.push_back("The marshaled result structure.");
+        }
+        else if(!amd)
+        {
+            returns = comment->returns();
+        }
+        postParams.push_back("@param " + currentParam + " The Current object for the invocation.");
+        writeOpDocSummary(H, p, comment, pt, true, StringList(), postParams, returns);
+    }
     H << nl << deprecateSymbol << "virtual " << retS << ' ' << opName << spar << params << epar << isConst << " = 0;";
+    H << nl << "/// \\cond INTERNAL";
     H << nl << "bool _iceD_" << name << "(::IceInternal::Incoming&, const "
       << getAbsolute("::Ice::Current&", classScope) << ")" << isConst << ';';
+    H << nl << "/// \\endcond";
 
     C << sp;
+    C << nl << "/// \\cond INTERNAL";
     C << nl << "bool";
     C << nl << scope.substr(2);
-    C << "_iceD_" << name << "(::IceInternal::Incoming& inS" << ", const " << getAbsolute("::Ice::Current&", classScope)
-      << " current)" << isConst;
+    C << "_iceD_" << name << "(::IceInternal::Incoming& inS, const "
+      << getAbsolute("::Ice::Current&", classScope) << " current)" << isConst;
     C << sb;
-    C << nl << "_iceCheckMode(" << getAbsolute(operationModeToString(p->mode(), true), classScope) << ", current.mode);";
+    C << nl << "_iceCheckMode(" << getAbsolute(operationModeToString(p->mode(), true), classScope)
+      << ", current.mode);";
 
     if(!inParams.empty())
     {
@@ -7354,6 +8372,7 @@ Slice::Gen::Cpp11InterfaceVisitor::visitOperation(const OperationPtr& p)
         C << nl << "return false;";
     }
     C << eb;
+    C << nl << "/// \\endcond";
 }
 
 Slice::Gen::Cpp11ValueVisitor::Cpp11ValueVisitor(::IceUtilInternal::Output& h,
@@ -7407,7 +8426,9 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefStart(const ClassDefPtr& p)
     DataMemberList dataMembers = p->dataMembers();
     DataMemberList allDataMembers = p->allDataMembers();
 
-    H << sp << nl << "class " << _dllClassExport << name << " : public " << getAbsolute("::Ice::ValueHelper", scope)
+    H << sp;
+    writeDocSummary(H, p);
+    H << nl << "class " << _dllClassExport << name << " : public " << getAbsolute("::Ice::ValueHelper", scope)
       << "<" << name << ", ";
 
     if(!base || (base && base->isInterface()))
@@ -7447,9 +8468,19 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefStart(const ClassDefPtr& p)
 
     emitOneShotConstructor(p);
 
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains a tuple containing all of the value's data members.";
+    H << nl << " * @return The data members in a tuple.";
+    H << nl << " */";
     writeIceTuple(H, fixKwd(p->scope()), p->allDataMembers(), _useWstring);
 
-    H << sp << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
+    H << sp;
+    H << nl << "/**";
+    H << nl << " * Obtains the Slice type ID of this value.";
+    H << nl << " * @return The fully-scoped type ID.";
+    H << nl << " */";
+    H << nl << _dllMemberExport << "static const ::std::string& ice_staticId();";
     return true;
 }
 
@@ -7470,7 +8501,14 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p)
 
     if(preserved && !basePreserved)
     {
-        H << sp << nl << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope)
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * Obtains the SlicedData object created when an unknown value type was marshaled";
+        H << nl << " * in the sliced format and the Ice run time sliced it to a known type.";
+        H << nl << " * @return The SlicedData object, or nil if the value was not sliced or was not";
+        H << nl << " * marshaled in the sliced format.";
+        H << nl << " */";
+        H << nl << "virtual ::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope)
           << "> ice_getSlicedData() const override;";
 
         C << sp;
@@ -7480,10 +8518,13 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p)
         C << eb;
 
         H << sp;
+        H << nl << "/// \\cond STREAM";
         H << nl << "virtual void _iceWrite(" << getAbsolute("::Ice::OutputStream*", scope) << ") const override;";
         H << nl << "virtual void _iceRead(" << getAbsolute("::Ice::InputStream*", scope) << ") override;";
+        H << nl << "/// \\endcond";
 
         C << sp;
+        C << nl << "/// \\cond STREAM";
         C << nl << "void" << nl << scoped.substr(2) << "::_iceWrite(" << getAbsolute("::Ice::OutputStream*", scope)
           << " ostr) const";
         C << sb;
@@ -7500,6 +8541,7 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p)
         C << nl << "_iceReadImpl(istr);";
         C << nl << "_iceSlicedData = istr->endValue(true);";
         C << eb;
+        C << nl << "/// \\endcond";
     }
 
     C << sp;
@@ -7565,7 +8607,10 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p)
             H.inc();
             inProtected = true;
         }
-        H << sp << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _iceSlicedData;";
+        H << sp;
+        H << nl << "/// \\cond STREAM";
+        H << nl << "::std::shared_ptr<" << getAbsolute("::Ice::SlicedData", scope) << "> _iceSlicedData;";
+        H << nl << "/// \\endcond";
     }
 
     if(generateFriend)
@@ -7595,7 +8640,10 @@ Slice::Gen::Cpp11ValueVisitor::visitClassDefEnd(const ClassDefPtr& p)
         // all of the globals in a compilation unit.
         //
         _doneStaticSymbol = true;
-        H << sp << nl << "static " << fixKwd(p->name()) << " _iceS_" << p->name() << "_init;";
+        H << sp;
+        H << nl << "/// \\cond INTERNAL";
+        H << nl << "static " << fixKwd(p->name()) << " _iceS_" << p->name() << "_init;";
+        H << nl << "/// \\endcond";
     }
 
     _useWstring = resetUseWstring(_useWstringHist);
@@ -7638,11 +8686,11 @@ Slice::Gen::Cpp11ObjectVisitor::emitVirtualBaseInitializers(const ClassDefPtr& d
         }
         if(isMovable((*q)->type()))
         {
-            upcall += "::std::move(iceP_" + (*q)->name() + ")";
+            upcall += "::std::move(" + fixKwd((*q)->name()) + ")";
         }
         else
         {
-            upcall += "iceP_" + (*q)->name();
+            upcall += "" + fixKwd((*q)->name());
         }
     }
     upcall += ")";
@@ -7668,6 +8716,7 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
     if(!allDataMembers.empty())
     {
         vector<string> allParamDecls;
+        map<string, CommentPtr> allComments;
         DataMemberList dataMembers = p->dataMembers();
 
         int typeContext = _useWstring | TypeContextCpp11;
@@ -7678,11 +8727,31 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
 
         for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
         {
-            string typeName = inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext);
-            allParamDecls.push_back(typeName + " iceP_" + (*q)->name());
+            string typeName =
+                inputTypeToString((*q)->type(), (*q)->optional(), scope, (*q)->getMetaData(), typeContext);
+            allParamDecls.push_back(typeName + " " + fixKwd((*q)->name()));
+            CommentPtr comment = (*q)->parseComment(false);
+            if(comment)
+            {
+                allComments[(*q)->name()] = comment;
+            }
         }
 
-        H << sp << nl;
+        CommentPtr comment = p->parseComment(false);
+
+        H << sp;
+        H << nl << "/**";
+        H << nl << " * One-shot constructor to initialize all data members.";
+        for(DataMemberList::const_iterator q = allDataMembers.begin(); q != allDataMembers.end(); ++q)
+        {
+            map<string, CommentPtr>::iterator r = allComments.find((*q)->name());
+            if(r != allComments.end())
+            {
+                H << nl << " * @param " << fixKwd(r->first) << " " << getDocSentence(r->second->overview());
+            }
+        }
+        H << nl << " */";
+        H << nl;
         if(allParamDecls.size() == 1)
         {
             H << "explicit ";
@@ -7717,11 +8786,11 @@ Slice::Gen::Cpp11ObjectVisitor::emitOneShotConstructor(const ClassDefPtr& p)
             string memberName = fixKwd((*q)->name());
             if(isMovable((*q)->type()))
             {
-                H << memberName << "(::std::move(iceP_" << (*q)->name() << "))";
+                H << memberName << "(::std::move(" << memberName << "))";
             }
             else
             {
-                H << memberName << "(iceP_" << (*q)->name() << ')';
+                H << memberName << "(" << memberName << ')';
             }
         }
 
@@ -7755,6 +8824,7 @@ Slice::Gen::Cpp11StreamVisitor::visitModuleStart(const ModulePtr& m)
         // Only emit this for the top-level module.
         //
         H << sp;
+        H << nl << "/// \\cond STREAM";
         H << nl << "namespace Ice" << nl << '{' << sp;
 
         if(m->hasNonLocalContained(Contained::ContainedTypeStruct))
@@ -7775,6 +8845,7 @@ Slice::Gen::Cpp11StreamVisitor::visitModuleEnd(const ModulePtr& m)
         // Only emit this for the top-level module.
         //
         H << nl << '}';
+        H << nl << "/// \\endcond";
         if(m->hasNonLocalContained(Contained::ContainedTypeStruct))
         {
             C << nl << '}';
@@ -7858,7 +8929,9 @@ Slice::Gen::Cpp11CompatibilityVisitor::visitModuleStart(const ModulePtr& p)
 
     string name = fixKwd(p->name());
 
-    H << sp << nl << "namespace " << name << nl << '{';
+    H << sp;
+    H << nl << "/// \\cond INTERNAL";
+    H << nl << "namespace " << name << nl << '{';
     return true;
 }
 
@@ -7867,6 +8940,7 @@ Slice::Gen::Cpp11CompatibilityVisitor::visitModuleEnd(const ModulePtr&)
 {
     H << sp;
     H << nl << '}';
+    H << nl << "/// \\endcond";
 }
 
 void
diff --git a/cpp/src/slice2cpp/Gen.h b/cpp/src/slice2cpp/Gen.h
index 9e8bca138b9..7e55bd3acc9 100644
--- a/cpp/src/slice2cpp/Gen.h
+++ b/cpp/src/slice2cpp/Gen.h
@@ -342,9 +342,11 @@ private:
         ::IceUtilInternal::Output& C;
         std::string _dllExport;
     };
+
     //
     // C++11 Visitors
     //
+
     class Cpp11DeclVisitor : private ::IceUtil::noncopyable, public ParserVisitor
     {
     public:
diff --git a/cpp/src/slice2cpp/Main.cpp b/cpp/src/slice2cpp/Main.cpp
index 622273e5658..d1482d3cbc0 100644
--- a/cpp/src/slice2cpp/Main.cpp
+++ b/cpp/src/slice2cpp/Main.cpp
@@ -298,7 +298,7 @@ compile(const vector<string>& argv)
         else
         {
             PreprocessorPtr icecpp = Preprocessor::create(argv[0], *i, cppArgs);
-            FILE* cppHandle = icecpp->preprocess(false, "-D__SLICE2CPP__");
+            FILE* cppHandle = icecpp->preprocess(true, "-D__SLICE2CPP__");
 
             if(cppHandle == 0)
             {
diff --git a/cpp/src/slice2java/Gen.cpp b/cpp/src/slice2java/Gen.cpp
index 9f15d3496f9..01d3e752ccb 100644
--- a/cpp/src/slice2java/Gen.cpp
+++ b/cpp/src/slice2java/Gen.cpp
@@ -220,7 +220,7 @@ Slice::JavaVisitor::getResultType(const OperationPtr& op, const string& package,
 }
 
 void
-Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const string& package, const DocCommentPtr& dc)
+Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const string& package, const CommentPtr& dc)
 {
     string opName = op->name();
     opName[0] = toupper(static_cast<unsigned char>(opName[0]));
@@ -286,16 +286,17 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
                 out << '.';
             }
 
-            if(ret && !dc->returns.empty())
+            if(ret && !dc->returns().empty())
             {
                 out << nl << " * @param " << retval << ' ';
-                writeDocCommentLines(out, dc->returns);
+                writeDocCommentLines(out, dc->returns());
             }
+            map<string, StringList> paramDocs = dc->parameters();
             for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p)
             {
                 const string name = (*p)->name();
-                map<string, string>::const_iterator q = dc->params.find(name);
-                if(q != dc->params.end() && !q->second.empty())
+                map<string, StringList>::const_iterator q = paramDocs.find(name);
+                if(q != paramDocs.end() && !q->second.empty())
                 {
                     out << nl << " * @param " << fixKwd(q->first) << ' ';
                     writeDocCommentLines(out, q->second);
@@ -308,14 +309,15 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
 
         if(ret)
         {
-            out << (typeToString(ret, TypeModeIn, package, op->getMetaData(), true, !generateMandatoryOnly && op->returnIsOptional(),
-                                 cl->isLocal()) + " " + retval);
+            out << (typeToString(ret, TypeModeIn, package, op->getMetaData(), true,
+                                 !generateMandatoryOnly && op->returnIsOptional(), cl->isLocal()) + " " + retval);
             needMandatoryOnly = !generateMandatoryOnly && op->returnIsOptional();
         }
         for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p)
         {
             out << (typeToString((*p)->type(), TypeModeIn, package, (*p)->getMetaData(), true,
-                                 !generateMandatoryOnly && (*p)->optional(), cl->isLocal()) + " " + fixKwd((*p)->name()));
+                                 !generateMandatoryOnly && (*p)->optional(), cl->isLocal()) + " " +
+                    fixKwd((*p)->name()));
             if(!generateMandatoryOnly)
             {
                 needMandatoryOnly = needMandatoryOnly || (*p)->optional();
@@ -358,11 +360,11 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
     out << sp;
     if(ret)
     {
-        if(dc && !dc->returns.empty())
+        if(dc && !dc->returns().empty())
         {
             out << nl << "/**";
             out << nl << " * ";
-            writeDocCommentLines(out, dc->returns);
+            writeDocCommentLines(out, dc->returns());
             out << nl << " **/";
         }
         out << nl << "public " << typeToString(ret, TypeModeIn, package, op->getMetaData(), true,
@@ -375,8 +377,9 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
         if(dc)
         {
             const string name = (*p)->name();
-            map<string, string>::const_iterator q = dc->params.find(name);
-            if(q != dc->params.end() && !q->second.empty())
+            map<string, StringList> paramDocs = dc->parameters();
+            map<string, StringList>::const_iterator q = paramDocs.find(name);
+            if(q != paramDocs.end() && !q->second.empty())
             {
                 out << nl << "/**";
                 out << nl << " * ";
@@ -401,13 +404,14 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
         for(ParamDeclList::const_iterator pli = required.begin(); pli != required.end(); ++pli)
         {
             const string paramName = fixKwd((*pli)->name());
-            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, true, iter, "",
-                                      (*pli)->getMetaData());
+            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, true,
+                                      iter, "", (*pli)->getMetaData());
         }
 
         if(ret && !op->returnIsOptional())
         {
-            writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, true, iter, "", op->getMetaData());
+            writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, true, iter, "",
+                                      op->getMetaData());
         }
 
         //
@@ -425,8 +429,8 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
             }
 
             const string paramName = fixKwd((*pli)->name());
-            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), "this." + paramName,
-                                      true, iter, "", (*pli)->getMetaData());
+            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(),
+                                      "this." + paramName, true, iter, "", (*pli)->getMetaData());
         }
 
         if(checkReturnType)
@@ -445,15 +449,15 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
         {
             const string paramName = fixKwd((*pli)->name());
             const string patchParams = getPatcher((*pli)->type(), package, "this." + paramName);
-            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, false, iter,
-                                      "", (*pli)->getMetaData(), patchParams);
+            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalNone, false, 0, "this." + paramName, false,
+                                      iter, "", (*pli)->getMetaData(), patchParams);
         }
 
         if(ret && !op->returnIsOptional())
         {
             const string patchParams = getPatcher(ret, package, retval);
-            writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, false, iter, "", op->getMetaData(),
-                                      patchParams);
+            writeMarshalUnmarshalCode(out, package, ret, OptionalNone, false, 0, retval, false, iter, "",
+                                      op->getMetaData(), patchParams);
         }
 
         //
@@ -473,8 +477,8 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
 
             const string paramName = fixKwd((*pli)->name());
             const string patchParams = getPatcher((*pli)->type(), package, paramName);
-            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(), "this." + paramName,
-                                      false, iter, "", (*pli)->getMetaData(), patchParams);
+            writeMarshalUnmarshalCode(out, package, (*pli)->type(), OptionalOutParam, true, (*pli)->tag(),
+                                      "this." + paramName, false, iter, "", (*pli)->getMetaData(), patchParams);
         }
 
         if(checkReturnType)
@@ -492,7 +496,7 @@ Slice::JavaVisitor::writeResultType(Output& out, const OperationPtr& op, const s
 
 void
 Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op, const string& package,
-                                             const DocCommentPtr& dc)
+                                             const CommentPtr& dc)
 {
     string opName = op->name();
     const TypePtr ret = op->returnType();
@@ -518,16 +522,17 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op
         out << nl << "/**";
         out << nl << " * This constructor marshals the results of operation " << opName << " immediately.";
 
-        if(ret && !dc->returns.empty())
+        if(ret && !dc->returns().empty())
         {
             out << nl << " * @param " << retval << ' ';
-            writeDocCommentLines(out, dc->returns);
+            writeDocCommentLines(out, dc->returns());
         }
+        map<string, StringList> paramDocs = dc->parameters();
         for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p)
         {
             const string name = (*p)->name();
-            map<string, string>::const_iterator q = dc->params.find(name);
-            if(q != dc->params.end() && !q->second.empty())
+            map<string, StringList>::const_iterator q = paramDocs.find(name);
+            if(q != paramDocs.end() && !q->second.empty())
             {
                 out << nl << " * @param " << fixKwd(q->first) << ' ';
                 writeDocCommentLines(out, q->second);
@@ -621,16 +626,17 @@ Slice::JavaVisitor::writeMarshaledResultType(Output& out, const OperationPtr& op
             out << nl << " * This constructor marshals the results of operation " << opName
                 << " immediately (overload without Optional parameters).";
 
-            if(ret && !dc->returns.empty())
+            if(ret && !dc->returns().empty())
             {
                 out << nl << " * @param " << retval << ' ';
-                writeDocCommentLines(out, dc->returns);
+                writeDocCommentLines(out, dc->returns());
             }
+            map<string, StringList> paramDocs = dc->parameters();
             for(ParamDeclList::const_iterator p = outParams.begin(); p != outParams.end(); ++p)
             {
                 const string name = (*p)->name();
-                map<string, string>::const_iterator q = dc->params.find(name);
-                if(q != dc->params.end() && !q->second.empty())
+                map<string, StringList>::const_iterator q = paramDocs.find(name);
+                if(q != paramDocs.end() && !q->second.empty())
                 {
                     out << nl << " * @param " << fixKwd(q->first) << ' ';
                     writeDocCommentLines(out, q->second);
@@ -1094,7 +1100,7 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
     {
         OperationPtr op = *r;
 
-        DocCommentPtr dc = parseDocComment(op);
+        CommentPtr dc = op->parseComment(false);
 
         //
         // The "MarshaledResult" type is generated in the servant interface.
@@ -1116,7 +1122,7 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
 
         out << sp;
         writeServantDocComment(out, op, package, dc, amd);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -1199,15 +1205,16 @@ Slice::JavaVisitor::writeDispatch(Output& out, const ClassDefPtr& p)
         OperationPtr op = *r;
         StringList opMetaData = op->getMetaData();
 
-        DocCommentPtr dc = parseDocComment(op);
+        CommentPtr dc = op->parseComment(false);
 
         string opName = op->name();
         out << sp;
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
-        out << nl << "static java.util.concurrent.CompletionStage<" << getAbsolute("com.zeroc.Ice.OutputStream", package)
+        out << nl << "static java.util.concurrent.CompletionStage<"
+            << getAbsolute("com.zeroc.Ice.OutputStream", package)
             << "> _iceD_" << opName << '(';
         if(p->isInterface())
         {
@@ -1735,189 +1742,26 @@ Slice::JavaVisitor::splitComment(const ContainedPtr& p)
     return result;
 }
 
-Slice::JavaVisitor::DocCommentPtr
-Slice::JavaVisitor::parseDocComment(const ContainedPtr& p)
+void
+Slice::JavaVisitor::writeDocCommentLines(Output& out, const StringList& lines)
 {
-    DocCommentPtr c = new DocComment;
-    c->deprecated = false;
-
     //
-    // First check metadata for a deprecated tag.
+    // This method emits a block of text, prepending a leading " * " to the second and
+    // subsequent lines. We assume the caller prepended a leading " * " for the first
+    // line if necessary.
     //
-    string deprecateMetadata;
-    if(p->findMetaData("deprecate", deprecateMetadata))
+    assert(!lines.empty());
+    StringList l = lines;
+    out << l.front();
+    l.pop_front();
+    for(StringList::const_iterator p = l.begin(); p != l.end(); ++p)
     {
-        c->deprecated = true;
-        if(deprecateMetadata.find("deprecate:") == 0 && deprecateMetadata.size() > 10)
+        out << nl << " *";
+        if(!p->empty())
         {
-            c->deprecateReason = IceUtilInternal::trim(deprecateMetadata.substr(10));
+            out << " " << *p;
         }
     }
-
-    const StringList lines = splitComment(p);
-    if(lines.empty())
-    {
-        return c->deprecated ? c : DocCommentPtr(0); // Docs exist if it's deprecated.
-    }
-
-    StringList::const_iterator i;
-    for(i = lines.begin(); i != lines.end(); ++i)
-    {
-        const string l = *i;
-        if(l[0] == '@')
-        {
-            break;
-        }
-        if(!c->overview.empty())
-        {
-            c->overview += "\n";
-        }
-        c->overview += l;
-    }
-
-    enum State { StateMisc, StateParam, StateThrows, StateReturn, StateDeprecated };
-    State state = StateMisc;
-    string name;
-    const string ws = " \t";
-    const string paramTag = "@param";
-    const string throwsTag = "@throws";
-    const string exceptionTag = "@exception";
-    const string returnTag = "@return";
-    const string deprecatedTag = "@deprecated";
-    for(; i != lines.end(); ++i)
-    {
-        const string l = *i;
-        if(l.find(paramTag) == 0)
-        {
-            state = StateMisc;
-            name.clear();
-            string::size_type n = l.find_first_not_of(ws, paramTag.size());
-            if(n == string::npos)
-            {
-                continue; // Malformed line, ignore it.
-            }
-            string::size_type end = l.find_first_of(ws, n);
-            if(end == string::npos)
-            {
-                continue; // Malformed line, ignore it.
-            }
-            name = l.substr(n, end - n);
-            state = StateParam;
-            n = l.find_first_not_of(ws, end);
-            if(n != string::npos)
-            {
-                c->params[name] = l.substr(n); // The first line of the description.
-            }
-        }
-        else if(l.find(throwsTag) == 0 || l.find(exceptionTag) == 0)
-        {
-            state = StateMisc;
-            name.clear();
-            string::size_type n =
-                l.find_first_not_of(ws, l.find(throwsTag) == 0 ? throwsTag.size() : exceptionTag.size());
-            if(n == string::npos)
-            {
-                continue; // Malformed line, ignore it.
-            }
-            string::size_type end = l.find_first_of(ws, n);
-            if(end == string::npos)
-            {
-                continue; // Malformed line, ignore it.
-            }
-            name = l.substr(n, end - n);
-            state = StateThrows;
-            n = l.find_first_not_of(ws, end);
-            if(n != string::npos)
-            {
-                c->exceptions[name] = l.substr(n); // The first line of the description.
-            }
-        }
-        else if(l.find(returnTag) == 0)
-        {
-            state = StateMisc;
-            name.clear();
-            string::size_type n = l.find_first_not_of(ws, returnTag.size());
-            if(n == string::npos)
-            {
-                continue; // Malformed line, ignore it.
-            }
-            state = StateReturn;
-            c->returns = l.substr(n); // The first line of the description.
-        }
-        else if(l.find(deprecatedTag) == 0)
-        {
-            state = StateMisc;
-            name.clear();
-            string::size_type n = l.find_first_not_of(ws, deprecatedTag.size());
-            if(n != string::npos)
-            {
-                c->deprecateReason = l.substr(n); // The first line of the description.
-            }
-            state = StateDeprecated;
-            c->deprecated = true;
-        }
-        else if(!l.empty())
-        {
-            if(l[0] == '@')
-            {
-                //
-                // Treat all other tags as miscellaneous comments.
-                //
-                state = StateMisc;
-            }
-
-            switch(state)
-            {
-            case StateMisc:
-                if(!c->misc.empty())
-                {
-                    c->misc += "\n";
-                }
-                c->misc += l;
-                break;
-            case StateParam:
-                assert(!name.empty());
-                if(c->params.find(name) == c->params.end())
-                {
-                    c->params[name] = "";
-                }
-                if(!c->params[name].empty())
-                {
-                    c->params[name] += "\n";
-                }
-                c->params[name] += l;
-                break;
-            case StateThrows:
-                assert(!name.empty());
-                if(c->exceptions.find(name) == c->exceptions.end())
-                {
-                    c->exceptions[name] = "";
-                }
-                if(!c->exceptions[name].empty())
-                {
-                    c->exceptions[name] += "\n";
-                }
-                c->exceptions[name] += l;
-                break;
-            case StateReturn:
-                if(!c->returns.empty())
-                {
-                    c->returns += "\n";
-                }
-                c->returns += l;
-                break;
-            case StateDeprecated:
-                if(!c->deprecateReason.empty())
-                {
-                    c->deprecateReason += "\n";
-                }
-                c->deprecateReason += l;
-                break;
-            }
-        }
-    }
-
-    return c;
 }
 
 void
@@ -1970,7 +1814,7 @@ Slice::JavaVisitor::writeDocCommentLines(Output& out, const string& text)
 }
 
 void
-Slice::JavaVisitor::writeDocComment(Output& out, const DocCommentPtr& dc)
+Slice::JavaVisitor::writeDocComment(Output& out, const CommentPtr& dc)
 {
     if(!dc)
     {
@@ -1978,22 +1822,36 @@ Slice::JavaVisitor::writeDocComment(Output& out, const DocCommentPtr& dc)
     }
 
     out << nl << "/**";
-    if(!dc->overview.empty())
+    if(!dc->overview().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->overview);
+        writeDocCommentLines(out, dc->overview());
     }
 
-    if(!dc->misc.empty())
+    if(!dc->misc().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->misc);
+        writeDocCommentLines(out, dc->misc());
+    }
+
+    if(!dc->seeAlso().empty())
+    {
+        out << nl << " *";
+        StringList sa = dc->seeAlso();
+        for(StringList::iterator p = sa.begin(); p != sa.end(); ++p)
+        {
+            out << nl << " * @see " << *p;
+        }
     }
 
-    if(!dc->deprecateReason.empty())
+    if(!dc->deprecated().empty())
     {
         out << nl << " * @deprecated ";
-        writeDocCommentLines(out, dc->deprecateReason);
+        writeDocCommentLines(out, dc->deprecated());
+    }
+    else if(dc->isDeprecated())
+    {
+        out << nl << " * @deprecated";
     }
 
     out << nl << " **/";
@@ -2013,7 +1871,7 @@ Slice::JavaVisitor::writeDocComment(Output& out, const string& text)
 
 void
 Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, const string& package,
-                                         const DocCommentPtr& dc, bool async, bool context)
+                                         const CommentPtr& dc, bool async, bool context)
 {
     if(!dc)
     {
@@ -2021,12 +1879,13 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
     }
 
     const string contextParam = " * @param context The Context map to send with the invocation.";
+    map<string, StringList> paramDocs = dc->parameters();
 
     out << nl << "/**";
-    if(!dc->overview.empty())
+    if(!dc->overview().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->overview);
+        writeDocCommentLines(out, dc->overview());
     }
 
     //
@@ -2036,8 +1895,8 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
     for(ParamDeclList::const_iterator i = paramList.begin(); i != paramList.end(); ++i)
     {
         const string name = (*i)->name();
-        map<string, string>::const_iterator j = dc->params.find(name);
-        if(j != dc->params.end() && !j->second.empty())
+        map<string, StringList>::const_iterator j = paramDocs.find(name);
+        if(j != paramDocs.end() && !j->second.empty())
         {
             out << nl << " * @param " << fixKwd(j->first) << ' ';
             writeDocCommentLines(out, j->second);
@@ -2065,10 +1924,10 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
     }
     else if(p->returnType())
     {
-        if(!dc->returns.empty())
+        if(!dc->returns().empty())
         {
             out << nl << " * @return ";
-            writeDocCommentLines(out, dc->returns);
+            writeDocCommentLines(out, dc->returns());
         }
         else if(async)
         {
@@ -2079,8 +1938,8 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
     {
         assert(p->outParameters().size() == 1);
         const ParamDeclPtr param = p->outParameters().front();
-        map<string, string>::const_iterator j = dc->params.find(param->name());
-        if(j != dc->params.end() && !j->second.empty())
+        map<string, StringList>::const_iterator j = paramDocs.find(param->name());
+        if(j != paramDocs.end() && !j->second.empty())
         {
             out << nl << " * @return ";
             writeDocCommentLines(out, j->second);
@@ -2103,23 +1962,38 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
     //
     if(!async)
     {
-        for(map<string, string>::const_iterator i = dc->exceptions.begin(); i != dc->exceptions.end(); ++i)
+        map<string, StringList> exDocs = dc->exceptions();
+        for(map<string, StringList>::const_iterator i = exDocs.begin(); i != exDocs.end(); ++i)
         {
             out << nl << " * @throws " << fixKwd(i->first) << ' ';
             writeDocCommentLines(out, i->second);
         }
     }
 
-    if(!dc->misc.empty())
+    if(!dc->misc().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->misc);
+        writeDocCommentLines(out, dc->misc());
+    }
+
+    if(!dc->seeAlso().empty())
+    {
+        out << nl << " *";
+        StringList sa = dc->seeAlso();
+        for(StringList::iterator p = sa.begin(); p != sa.end(); ++p)
+        {
+            out << nl << " * @see " << *p;
+        }
     }
 
-    if(!dc->deprecateReason.empty())
+    if(!dc->deprecated().empty())
     {
         out << nl << " * @deprecated ";
-        writeDocCommentLines(out, dc->deprecateReason);
+        writeDocCommentLines(out, dc->deprecated());
+    }
+    else if(dc->isDeprecated())
+    {
+        out << nl << " * @deprecated";
     }
 
     out << nl << " **/";
@@ -2127,22 +2001,23 @@ Slice::JavaVisitor::writeProxyDocComment(Output& out, const OperationPtr& p, con
 
 void
 Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, const string& package,
-                                           const DocCommentPtr& dc, bool async)
+                                           const CommentPtr& dc, bool async)
 {
     if(!dc)
     {
         return;
     }
 
+    map<string, StringList> paramDocs = dc->parameters();
     const ParamDeclList paramList = p->inParameters();
     const string currentParamName = getEscapedParamName(p, "current");
     const string currentParam = " * @param " + currentParamName + " The Current object for the invocation.";
 
     out << nl << "/**";
-    if(!dc->overview.empty())
+    if(!dc->overview().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->overview);
+        writeDocCommentLines(out, dc->overview());
     }
 
     //
@@ -2151,8 +2026,8 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c
     for(ParamDeclList::const_iterator i = paramList.begin(); i != paramList.end(); ++i)
     {
         const string name = (*i)->name();
-        map<string, string>::const_iterator j = dc->params.find(name);
-        if(j != dc->params.end() && !j->second.empty())
+        map<string, StringList>::const_iterator j = paramDocs.find(name);
+        if(j != paramDocs.end() && !j->second.empty())
         {
             out << nl << " * @param " << fixKwd(j->first) << ' ';
             writeDocCommentLines(out, j->second);
@@ -2178,10 +2053,10 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c
     }
     else if(p->returnType())
     {
-        if(!dc->returns.empty())
+        if(!dc->returns().empty())
         {
             out << nl << " * @return ";
-            writeDocCommentLines(out, dc->returns);
+            writeDocCommentLines(out, dc->returns());
         }
         else if(async)
         {
@@ -2192,8 +2067,8 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c
     {
         assert(p->outParameters().size() == 1);
         const ParamDeclPtr param = p->outParameters().front();
-        map<string, string>::const_iterator j = dc->params.find(param->name());
-        if(j != dc->params.end() && !j->second.empty())
+        map<string, StringList>::const_iterator j = paramDocs.find(param->name());
+        if(j != paramDocs.end() && !j->second.empty())
         {
             out << nl << " * @return ";
             writeDocCommentLines(out, j->second);
@@ -2217,23 +2092,38 @@ Slice::JavaVisitor::writeServantDocComment(Output& out, const OperationPtr& p, c
     }
     else
     {
-        for(map<string, string>::const_iterator i = dc->exceptions.begin(); i != dc->exceptions.end(); ++i)
+        map<string, StringList> exDocs = dc->exceptions();
+        for(map<string, StringList>::const_iterator i = exDocs.begin(); i != exDocs.end(); ++i)
         {
             out << nl << " * @throws " << fixKwd(i->first) << ' ';
             writeDocCommentLines(out, i->second);
         }
     }
 
-    if(!dc->misc.empty())
+    if(!dc->misc().empty())
     {
         out << nl << " * ";
-        writeDocCommentLines(out, dc->misc);
+        writeDocCommentLines(out, dc->misc());
+    }
+
+    if(!dc->seeAlso().empty())
+    {
+        out << nl << " *";
+        StringList sa = dc->seeAlso();
+        for(StringList::iterator p = sa.begin(); p != sa.end(); ++p)
+        {
+            out << nl << " * @see " << *p;
+        }
     }
 
-    if(!dc->deprecateReason.empty())
+    if(!dc->deprecated().empty())
     {
         out << nl << " * @deprecated ";
-        writeDocCommentLines(out, dc->deprecateReason);
+        writeDocCommentLines(out, dc->deprecated());
+    }
+    else if(dc->isDeprecated())
+    {
+        out << nl << " * @deprecated";
     }
 
     out << nl << " **/";
@@ -2400,14 +2290,14 @@ Slice::Gen::TypesVisitor::visitClassDefStart(const ClassDefPtr& p)
         }
     }
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
 
     //
     // Slice interfaces map to Java interfaces.
     //
     out << sp;
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -2778,7 +2668,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p)
 
     Output& out = output();
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
 
     //
     // Generate the "Result" type needed by operations that return multiple values.
@@ -2809,7 +2699,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p)
         out << sp;
 
         writeProxyDocComment(out, p, package, dc, false, false);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -2829,7 +2719,7 @@ Slice::Gen::TypesVisitor::visitOperation(const OperationPtr& p)
         {
             out << sp;
             writeProxyDocComment(out, p, package, dc, true, false);
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -2860,9 +2750,9 @@ Slice::Gen::TypesVisitor::visitExceptionStart(const ExceptionPtr& p)
 
     out << sp;
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -3313,9 +3203,9 @@ Slice::Gen::TypesVisitor::visitStructStart(const StructPtr& p)
 
     out << sp;
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -3696,9 +3586,9 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
 
     out << sp;
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -3762,7 +3652,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
         //
         out << sp;
         writeDocComment(out, dc);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -3783,7 +3673,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
         //
         out << sp;
         writeDocComment(out, dc);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -3803,7 +3693,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
         {
             out << sp;
             writeDocComment(out, dc);
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -3814,7 +3704,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
 
             out << sp;
             writeDocComment(out, dc);
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -3828,7 +3718,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
 
             out << sp;
             writeDocComment(out, dc);
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -3862,7 +3752,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
 
             out << sp;
             writeDocComment(out, dc);
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -3923,7 +3813,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
                 return;
             }
             out << sp;
-            if(dc && dc->deprecated)
+            if(dc && dc->isDeprecated())
             {
                 out << nl << "@Deprecated";
             }
@@ -3962,7 +3852,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
                 // Indexed getter.
                 //
                 out << sp;
-                if(dc && dc->deprecated)
+                if(dc && dc->isDeprecated())
                 {
                     out << nl << "@Deprecated";
                 }
@@ -3982,7 +3872,7 @@ Slice::Gen::TypesVisitor::visitDataMember(const DataMemberPtr& p)
                 // Indexed setter.
                 //
                 out << sp;
-                if(dc && dc->deprecated)
+                if(dc && dc->isDeprecated())
                 {
                     out << nl << "@Deprecated";
                 }
@@ -4016,9 +3906,9 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p)
 
     out << sp;
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -4036,9 +3926,9 @@ Slice::Gen::TypesVisitor::visitEnum(const EnumPtr& p)
         {
             out << ',';
         }
-        DocCommentPtr edc = parseDocComment(*en);
+        CommentPtr edc = (*en)->parseComment(false);
         writeDocComment(out, edc);
-        if(edc && edc->deprecated)
+        if(edc && edc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -4168,9 +4058,9 @@ Slice::Gen::TypesVisitor::visitConst(const ConstPtr& p)
 
     out << sp;
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -4599,14 +4489,14 @@ Slice::Gen::ProxyVisitor::visitClassDefStart(const ClassDefPtr& p)
         bases.pop_front();
     }
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
 
     //
     // Generate a Java interface as the user-visible type
     //
     out << sp;
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -4639,7 +4529,7 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
 {
     Output& out = output();
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
 
     const string package = getPackage(p);
     const string contextParam = "java.util.Map<String, String> context";
@@ -4650,7 +4540,8 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
                     "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 << "static " << p->name() << "Prx checkedCast(" << getAbsolute("com.zeroc.Ice.ObjectPrx", package) << " obj)";
+    out << nl << "static " << p->name() << "Prx checkedCast(" << getAbsolute("com.zeroc.Ice.ObjectPrx", package)
+        << " obj)";
     out << sb;
     out << nl << "return " << getAbsolute("com.zeroc.Ice.ObjectPrx", package) << "._checkedCast(obj, ice_staticId(), "
         << p->name() << "Prx.class, _" << p->name() << "PrxI.class);";
@@ -4976,7 +4867,7 @@ Slice::Gen::ProxyVisitor::visitClassDefEnd(const ClassDefPtr& p)
     Output& outi = output();
 
     outi << sp;
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         outi << nl << "@Deprecated";
     }
@@ -5031,14 +4922,14 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     const string contextParam = "java.util.Map<String, String> " + contextParamName;
     const string noExplicitContextArg = "com.zeroc.Ice.ObjectPrx.noExplicitContext";
 
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
 
     //
     // Synchronous methods with required parameters.
     //
     out << sp;
     writeProxyDocComment(out, p, package, dc, false, false);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -5055,7 +4946,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
     out << sp;
     writeProxyDocComment(out, p, package, dc, false, true);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -5104,7 +4995,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
     {
         out << sp;
         writeProxyDocComment(out, p, package, dc, false, false);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -5121,7 +5012,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
         out << sp;
         writeProxyDocComment(out, p, package, dc, false, true);
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -5173,19 +5064,20 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
     const string future = getFutureType(p, package);
 
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
     out << nl << "default " << future << ' ' << p->name() << "Async" << spar << params << epar;
     out << sb;
-    out << nl << "return _iceI_" << p->name() << "Async" << spar << args << noExplicitContextArg << "false" << epar << ';';
+    out << nl << "return _iceI_" << p->name() << "Async" << spar << args << noExplicitContextArg << "false" << epar
+        << ';';
     out << eb;
 
     out << sp;
     writeProxyDocComment(out, p, package, dc, true, true);
 
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
@@ -5261,7 +5153,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
 
         const string future = getFutureType(p, package);
 
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -5274,7 +5166,7 @@ Slice::Gen::ProxyVisitor::visitOperation(const OperationPtr& p)
         out << sp;
         writeProxyDocComment(out, p, package, dc, true, true);
 
-        if(dc && dc->deprecated)
+        if(dc && dc->isDeprecated())
         {
             out << nl << "@Deprecated";
         }
@@ -5349,9 +5241,9 @@ Slice::Gen::DispatcherVisitor::visitClassDefStart(const ClassDefPtr& p)
     Output& out = output();
 
     out << sp;
-    DocCommentPtr dc = parseDocComment(p);
+    CommentPtr dc = p->parseComment(false);
     writeDocComment(out, dc);
-    if(dc && dc->deprecated)
+    if(dc && dc->isDeprecated())
     {
         out << nl << "@Deprecated";
     }
diff --git a/cpp/src/slice2java/Gen.h b/cpp/src/slice2java/Gen.h
index 1850a3b0dfc..262c90e65b0 100644
--- a/cpp/src/slice2java/Gen.h
+++ b/cpp/src/slice2java/Gen.h
@@ -29,22 +29,10 @@ protected:
 
     enum ParamDir { InParam, OutParam };
 
-    struct DocComment : public IceUtil::SimpleShared
-    {
-        std::string overview;
-        std::map<std::string, std::string> params;
-        std::map<std::string, std::string> exceptions;
-        std::string returns;
-        bool deprecated;
-        std::string deprecateReason;
-        std::string misc;
-    };
-    typedef IceUtil::Handle<DocComment> DocCommentPtr;
-
     std::string getResultType(const OperationPtr&, const std::string&, bool, bool);
-    void writeResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const DocCommentPtr&);
+    void writeResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const CommentPtr&);
     void writeMarshaledResultType(::IceUtilInternal::Output&, const OperationPtr&, const std::string&,
-                                  const DocCommentPtr&);
+                                  const CommentPtr&);
 
     void allocatePatcher(::IceUtilInternal::Output&, const TypePtr&, const std::string&, const std::string&, bool);
     std::string getPatcher(const TypePtr&, const std::string&, const std::string&);
@@ -112,14 +100,14 @@ protected:
     // Handle doc comments.
     //
     static StringList splitComment(const ContainedPtr&);
-    DocCommentPtr parseDocComment(const ContainedPtr&);
+    void writeDocCommentLines(::IceUtilInternal::Output&, const StringList&);
     void writeDocCommentLines(::IceUtilInternal::Output&, const std::string&);
-    void writeDocComment(::IceUtilInternal::Output&, const DocCommentPtr&);
+    void writeDocComment(::IceUtilInternal::Output&, const CommentPtr&);
     void writeDocComment(::IceUtilInternal::Output&, const std::string&);
-    void writeProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const DocCommentPtr&,
+    void writeProxyDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&, const CommentPtr&,
                               bool, bool);
     void writeServantDocComment(::IceUtilInternal::Output&, const OperationPtr&, const std::string&,
-                                const DocCommentPtr&, bool);
+                                const CommentPtr&, bool);
 };
 
 class Gen : private ::IceUtil::noncopyable