zeroc-ice 3.6.1 → 3.6.2

data/ext/ice/cpp/src/IceUtil/UUID.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/IceUtil/Unicode.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -128,4 +128,60 @@ IceUtilInternal::convertUTF8ToUTFWstring(const Byte*& sourceStart, const Byte* s
     return result;
 }
 
+ConversionResult
+IceUtilInternal::convertUTF8ToUTF16(const vector<unsigned char>& source, vector<unsigned short>& target, ConversionFlags flags)
+{
+    target.resize(source.size());
+    const unsigned char* sourceStart = &source[0];
+    const unsigned char* sourceEnd = &source[0] + source.size();
+    
+    unsigned short* targetStart = &target[0]; 
+    unsigned short* targetEnd = &target[0] + target.size();
+    ConversionResult result = ConvertUTF8toUTF16(&sourceStart, sourceEnd, &targetStart, targetEnd, flags);
+    
+    if(result == conversionOK)
+    {
+        target.resize(targetStart - &target[0]);
+    }
+    return result;
+}
+
+ConversionResult
+IceUtilInternal::convertUTF8ToUTF32(const vector<unsigned char>& source, vector<unsigned int>& target, ConversionFlags flags)
+{
+    target.resize(source.size());
+    const unsigned char* sourceStart = &source[0];
+    const unsigned char* sourceEnd = &source[0] + source.size();
+    
+    unsigned int* targetStart = &target[0]; 
+    unsigned int* targetEnd = &target[0] + target.size();
+    ConversionResult result = ConvertUTF8toUTF32(&sourceStart, sourceEnd, &targetStart, targetEnd, flags);
+    
+    if(result == conversionOK)
+    {
+        target.resize(targetStart - &target[0]);
+    }
+    return result;
+}
+
+ConversionResult
+IceUtilInternal::convertUTF32ToUTF8(const vector<unsigned int>& source, vector<unsigned char>& target, ConversionFlags flags)
+{
+    target.resize(source.size() * 4);
+
+    const unsigned int* sourceStart = &source[0];
+    const unsigned int* sourceEnd = &source[0] + source.size();
+    
+    unsigned char* targetStart = &target[0]; 
+    unsigned char* targetEnd = &target[0] + target.size();
+    ConversionResult result = ConvertUTF32toUTF8(&sourceStart, sourceEnd, &targetStart, targetEnd, flags);
+    
+    if(result == conversionOK)
+    {
+        target.resize(targetStart - &target[0]);
+    }
+    return result;
+}
+
+
 

data/ext/ice/cpp/src/IceUtil/Unicode.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -44,6 +44,19 @@ ConversionResult
 convertUTF8ToUTFWstring(const IceUtil::Byte*& sourceStart, const IceUtil::Byte* sourceEnd, 
                         std::wstring& target, IceUtil::ConversionFlags flags);
 
+
+ICE_UTIL_API ConversionResult
+convertUTF8ToUTF16(const std::vector<unsigned char>&, std::vector<unsigned short>&,
+                   IceUtil::ConversionFlags);
+
+ICE_UTIL_API ConversionResult
+convertUTF8ToUTF32(const std::vector<unsigned char>&, std::vector<unsigned int>&,
+                   IceUtil::ConversionFlags);
+
+ICE_UTIL_API ConversionResult
+convertUTF32ToUTF8(const std::vector<unsigned int>&, std::vector<unsigned char>&,
+                   IceUtil::ConversionFlags);
+
 }
 
 #endif

data/ext/ice/cpp/src/Slice/CPlusPlusUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -383,7 +383,7 @@ Slice::printHeader(Output& out)
     static const char* header =
 "// **********************************************************************\n"
 "//\n"
-"// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.\n"
+"// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.\n"
 "//\n"
 "// This copy of Ice is licensed to you under the terms described in the\n"
 "// ICE_LICENSE file included in this distribution.\n"

data/ext/ice/cpp/src/Slice/Checksum.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/CsUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/DotNetNames.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/FileTracker.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/Grammar.cpp

@@ -81,7 +81,7 @@
 
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/GrammarUtil.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/JavaUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -286,7 +286,7 @@ Slice::JavaOutput::printHeader()
     static const char* header =
 "// **********************************************************************\n"
 "//\n"
-"// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.\n"
+"// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.\n"
 "//\n"
 "// This copy of Ice is licensed to you under the terms described in the\n"
 "// ICE_LICENSE file included in this distribution.\n"

data/ext/ice/cpp/src/Slice/MD5.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/MD5.h

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/ObjCUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/PHPUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/Parser.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/Preprocessor.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/Python.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.

data/ext/ice/cpp/src/Slice/PythonUtil.cpp

@@ -1,6 +1,6 @@
 // **********************************************************************
 //
-// Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.
+// Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.
 //
 // This copy of Ice is licensed to you under the terms described in the
 // ICE_LICENSE file included in this distribution.
@@ -13,6 +13,7 @@
 #include <IceUtil/IceUtil.h>
 #include <IceUtil/StringUtil.h>
 #include <IceUtil/InputUtil.h>
+#include <IceUtil/Unicode.h>
 #include <climits>
 #include <iterator>
 
@@ -164,7 +165,27 @@ private:
     void collectClassMembers(const ClassDefPtr&, MemberInfoList&, bool);
     void collectExceptionMembers(const ExceptionPtr&, MemberInfoList&, bool);
 
-    string editComment(const string&);
+    typedef vector<string> StringVec;
+
+    StringVec stripMarkup(const string&);
+
+    void writeDocstring(const string&, const string& = "");
+    void writeDocstring(const string&, const DataMemberList&);
+    void writeDocstring(const string&, const EnumeratorList&);
+
+    typedef map<string, string> StringMap;
+    struct OpComment
+    {
+        StringVec description;
+        StringMap params;
+        string returns;
+        StringMap exceptions;
+    };
+    bool parseOpComment(const string&, OpComment&);
+
+    enum DocstringMode { DocSync, DocAsyncBegin, DocAsyncEnd, DocDispatch, DocAsyncDispatch };
+
+    void writeDocstring(const OperationPtr&, DocstringMode, bool);
 
     Output& _out;
     set<string>& _moduleHistory;
@@ -351,11 +372,7 @@ Slice::Python::CodeVisitor::visitModuleStart(const ModulePtr& p)
     }
     _out << nl << "__name__ = '" << abs << "'";
 
-    string comment = p->comment();
-    if(!comment.empty())
-    {
-        _out << nl << "_M_" << abs << ".__doc__ = '''" << editComment(comment) << "'''";
-    }
+    writeDocstring(p->comment(), "_M_" + abs + ".__doc__ = ");
 
     _moduleStack.push_front(abs);
     return true;
@@ -448,11 +465,7 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
 
     _out.inc();
 
-    string comment = p->comment();
-    if(!comment.empty())
-    {
-        _out << nl << "'''" << editComment(comment) << "'''";
-    }
+    writeDocstring(p->comment(), p->dataMembers());
 
     //
     // __init__
@@ -581,11 +594,9 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
                 }
                 _out << "):";
                 _out.inc();
-                comment = (*oli)->comment();
-                if(!comment.empty())
-                {
-                    _out << nl << "'''" << editComment(comment) << "'''";
-                }
+
+                writeDocstring(*oli, DocAsyncDispatch, false);
+
                 _out << nl << "pass";
                 _out.dec();
             }
@@ -608,11 +619,7 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
                 }
                 _out << "):";
                 _out.inc();
-                comment = (*oli)->comment();
-                if(!comment.empty())
-                {
-                    _out << nl << "'''" << editComment(comment) << "'''";
-                }
+                writeDocstring(*oli, DocDispatch, p->isLocal());
                 _out << nl << "pass";
                 _out.dec();
             }
@@ -679,17 +686,8 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
                 }
             }
 
-            comment = (*oli)->comment();
-            if(!comment.empty())
-            {
-                comment = "'''" + editComment(comment) + "'''";
-            }
-
             _out << sp;
-            if(!comment.empty())
-            {
-                _out << nl << comment;
-            }
+            writeDocstring(*oli, DocSync, false);
             _out << nl << "def " << fixedOpName << "(self";
             if(!inParams.empty())
             {
@@ -709,10 +707,7 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
             // Async operations.
             //
             _out << sp;
-            if(!comment.empty())
-            {
-                _out << nl << comment;
-            }
+            writeDocstring(*oli, DocAsyncBegin, false);
             _out << nl << "def begin_" << (*oli)->name() << "(self";
             if(!inParams.empty())
             {
@@ -729,10 +724,7 @@ Slice::Python::CodeVisitor::visitClassDefStart(const ClassDefPtr& p)
             _out.dec();
 
             _out << sp;
-            if(!comment.empty())
-            {
-                _out << nl << comment;
-            }
+            writeDocstring(*oli, DocAsyncEnd, false);
             _out << nl << "def end_" << (*oli)->name() << "(self, _r):";
             _out.inc();
             _out << nl << "return _M_" << abs << "._op_" << (*oli)->name() << ".end(self, _r)";
@@ -1031,14 +1023,10 @@ Slice::Python::CodeVisitor::visitExceptionStart(const ExceptionPtr& p)
     _out << "):";
     _out.inc();
 
-    string comment = p->comment();
-    if(!comment.empty())
-    {
-        _out << nl << "'''" << editComment(comment) << "'''";
-    }
-
     DataMemberList members = p->dataMembers();
 
+    writeDocstring(p->comment(), members);
+
     //
     // __init__
     //
@@ -1159,10 +1147,10 @@ Slice::Python::CodeVisitor::visitStructStart(const StructPtr& p)
     string scoped = p->scoped();
     string abs = getAbsolute(p);
     string name = fixIdent(p->name());
+    DataMemberList members = p->dataMembers();
     MemberInfoList memberList;
 
     {
-        DataMemberList members = p->dataMembers();
         for(DataMemberList::iterator q = members.begin(); q != members.end(); ++q)
         {
             memberList.push_back(MemberInfo());
@@ -1178,11 +1166,7 @@ Slice::Python::CodeVisitor::visitStructStart(const StructPtr& p)
     _out << nl << "class " << name << "(object):";
     _out.inc();
 
-    string comment = p->comment();
-    if(!comment.empty())
-    {
-        _out << nl << "'''" << editComment(comment) << "'''";
-    }
+    writeDocstring(p->comment(), members);
 
     _out << nl << "def __init__(self";
     writeConstructorParams(memberList);
@@ -1512,11 +1496,7 @@ Slice::Python::CodeVisitor::visitEnum(const EnumPtr& p)
     _out << nl << "class " << name << "(Ice.EnumBase):";
     _out.inc();
 
-    string comment = p->comment();
-    if(!comment.empty())
-    {
-        _out << nl << "'''" << editComment(comment) << "'''";
-    }
+    writeDocstring(p->comment(), enums);
 
     _out << sp << nl << "def __init__(self, _n, _v):";
     _out.inc();
@@ -1879,68 +1859,138 @@ Slice::Python::CodeVisitor::writeConstantValue(const TypePtr& type, const Syntax
 
                 _out << "\"";                                       // Opening "
 
-                for(string::const_iterator c = value.begin(); c != value.end(); ++c)
+                for(size_t i = 0; i < value.size();)
                 {
-                    switch(*c)
-                    {
-                    case '"':
+                    char c = value[i];
+                    switch(c)
                     {
-                        _out << "\\\"";
-                        break;
-                    }
-                    case '\\':
-                    {
-                        _out << "\\\\";
-                        break;
-                    }
-                    case '\r':
-                    {
-                        _out << "\\r";
-                        break;
-                    }
-                    case '\n':
-                    {
-                        _out << "\\n";
-                        break;
-                    }
-                    case '\t':
-                    {
-                        _out << "\\t";
-                        break;
-                    }
-                    case '\b':
-                    {
-                        _out << "\\b";
-                        break;
-                    }
-                    case '\f':
-                    {
-                        _out << "\\f";
-                        break;
-                    }
-                    default:
-                    {
-                        if(charSet.find(*c) == charSet.end())
+                        case '"':
                         {
-                            unsigned char uc = *c;              // Char may be signed, so make it positive.
-                            stringstream s;
-                            s << "\\";                          // Print as octal if not in basic source character set.
-                            s.flags(ios_base::oct);
-                            s.width(3);
-                            s.fill('0');
-                            s << static_cast<unsigned>(uc);
-                            _out << s.str();
+                            _out << "\\\"";
+                            break;
                         }
-                        else
+                        case '\\':
                         {
-                            _out << *c;                         // Print normally if in basic source character set.
+                            string s = "\\";
+                            size_t j = i + 1;
+                            for(; j < value.size(); ++j)
+                            {
+                                if(value[j] != '\\')
+                                {
+                                    break;
+                                }
+                                s += "\\";
+                            }
+
+                            //
+                            // An even number of slash \ will escape the backslash and
+                            // the codepoint will be interpreted as its charaters
+                            //
+                            // \\u00000041  - ['\\', 'u', '0', '0', '0', '0', '0', '0', '4', '1']
+                            // \\\u00000041 - ['\\', 'A'] (41 is the codepoint for 'A')
+                            //
+                            if(s.size() % 2 != 0 && (value[j] == 'U' || value[j] == 'u'))
+                            {
+                                //
+                                // Convert codepoint to UTF8 bytes and write the escaped bytes
+                                //
+                                _out << s.substr(0, s.size() - 1);
+
+                                size_t sz = value[j] == 'U' ? 8 : 4;
+                                string codepoint = value.substr(j + 1, sz);
+                                assert(codepoint.size() ==  sz);
+
+                                IceUtil::Int64 v = IceUtilInternal::strToInt64(codepoint.c_str(), 0, 16);
+
+                                vector<unsigned int> u32buffer;
+                                u32buffer.push_back(static_cast<unsigned int>(v));
+
+                                vector<unsigned char> u8buffer;
+                                IceUtilInternal::ConversionResult result = convertUTF32ToUTF8(u32buffer, u8buffer, IceUtil::lenientConversion);
+                                switch(result)
+                                {
+                                    case conversionOK:
+                                        break;
+                                    case sourceExhausted:
+                                        throw IceUtil::IllegalConversionException(__FILE__, __LINE__, "string source exhausted");
+                                    case sourceIllegal:
+                                        throw IceUtil::IllegalConversionException(__FILE__, __LINE__, "string source illegal");
+                                    default:
+                                    {
+                                        assert(0);
+                                        throw IceUtil::IllegalConversionException(__FILE__, __LINE__);
+                                    }
+                                }
+
+                                ostringstream s;
+                                for(vector<unsigned char>::const_iterator q = u8buffer.begin(); q != u8buffer.end(); ++q)
+                                {
+                                    s << "\\";
+                                    s.fill('0');
+                                    s.width(3);
+                                    s << oct;
+                                    s << static_cast<unsigned int>(*q);
+                                }
+                                _out << s.str();
+
+                                i = j + 1 + sz;
+                            }
+                            else
+                            {
+                                _out << s;
+                                i = j;
+                            }
+                            continue;
+                        }
+                        case '\r':
+                        {
+                            _out << "\\r";
+                            break;
+                        }
+                        case '\n':
+                        {
+                            _out << "\\n";
+                            break;
+                        }
+                        case '\t':
+                        {
+                            _out << "\\t";
+                            break;
+                        }
+                        case '\b':
+                        {
+                            _out << "\\b";
+                            break;
+                        }
+                        case '\f':
+                        {
+                            _out << "\\f";
+                            break;
+                        }
+                        default:
+                        {
+                            if(charSet.find(c) == charSet.end())
+                            {
+                                unsigned char uc = c;               // Char may be signed, so make it positive.
+                                stringstream s;
+                                s << "\\";                          // Print as octal if not in basic source character set.
+                                s.flags(ios_base::oct);
+                                s.width(3);
+                                s.fill('0');
+                                s << static_cast<unsigned>(uc);
+                                _out << s.str();
+                            }
+                            else
+                            {
+                                _out << c;                          // Print normally if in basic source character set.
+                            }
+                            break;
                         }
-                        break;
-                    }
                     }
+                    ++i;
                 }
 
-                _out << "\"";                                   // Closing "
+                _out << "\"";                                       // Closing "
                 break;
             }
             case Slice::Builtin::KindObject:
@@ -2062,25 +2112,25 @@ Slice::Python::CodeVisitor::collectExceptionMembers(const ExceptionPtr& p, Membe
     }
 }
 
-string
-Slice::Python::CodeVisitor::editComment(const string& comment)
+Slice::Python::CodeVisitor::StringVec
+Slice::Python::CodeVisitor::stripMarkup(const string& comment)
 {
     //
     // Strip HTML markup and javadoc links.
     //
-    string result = comment;
+    string text = comment;
     string::size_type pos = 0;
     do
     {
-        pos = result.find('<', pos);
+        pos = text.find('<', pos);
         if(pos != string::npos)
         {
-            string::size_type endpos = result.find('>', pos);
+            string::size_type endpos = text.find('>', pos);
             if(endpos == string::npos)
             {
                 break;
             }
-            result.erase(pos, endpos - pos + 1);
+            text.erase(pos, endpos - pos + 1);
         }
     } while(pos != string::npos);
 
@@ -2088,18 +2138,18 @@ Slice::Python::CodeVisitor::editComment(const string& comment)
     pos = 0;
     do
     {
-        pos = result.find(link, pos);
+        pos = text.find(link, pos);
         if(pos != string::npos)
         {
-            result.erase(pos, link.size());
-            string::size_type endpos = result.find('}', pos);
+            text.erase(pos, link.size());
+            string::size_type endpos = text.find('}', pos);
             if(endpos != string::npos)
             {
-                string::size_type identpos = result.find_first_not_of(" \t#", pos);
+                string::size_type identpos = text.find_first_not_of(" \t#", pos);
                 if(identpos != string::npos && identpos < endpos)
                 {
-                    string ident = result.substr(identpos, endpos - identpos);
-                    result.replace(pos, endpos - pos + 1, fixIdent(ident));
+                    string ident = text.substr(identpos, endpos - identpos);
+                    text.replace(pos, endpos - pos + 1, fixIdent(ident));
                 }
             }
         }
@@ -2116,160 +2166,639 @@ Slice::Python::CodeVisitor::editComment(const string& comment)
         // Look for the next @ and delete up to that, or
         // to the end of the string, if not found.
         //
-        pos = result.find(seeTag, pos);
+        pos = text.find(seeTag, pos);
         if(pos != string::npos)
         {
-            string::size_type next = result.find('@', pos + seeTag.size());
+            string::size_type next = text.find('@', pos + seeTag.size());
             if(next != string::npos)
             {
-                result.erase(pos, next - pos);
+                text.erase(pos, next - pos);
             }
             else
             {
-                result.erase(pos, string::npos);
+                text.erase(pos, string::npos);
             }
         }
     } while(pos != string::npos);
 
     //
-    // Reformat @param, @return, and @throws.
+    // Escape triple quotes.
     //
-    static const string paramTag = "@param";
+    static const string singleQuotes = "'''";
     pos = 0;
-    bool first = true;
-    do
+    while((pos = text.find(singleQuotes, pos)) != string::npos)
     {
-        pos = result.find(paramTag, pos);
-        if(pos != string::npos)
+        text.insert(pos, "\\");
+        pos += singleQuotes.size() + 1;
+    }
+    static const string doubleQuotes = "\"\"\"";
+    pos = 0;
+    while((pos = text.find(doubleQuotes, pos)) != string::npos)
+    {
+        text.insert(pos, "\\");
+        pos += doubleQuotes.size() + 1;
+    }
+
+    //
+    // Fold multiple empty lines.
+    //
+    pos = 0;
+    while(true)
+    {
+        pos = text.find('\n', pos);
+        if(pos == string::npos)
+        {
+            break;
+        }
+
+        //
+        // Skip the next LF or CR/LF, if present.
+        //
+        if(pos < text.size() - 1 && text[pos + 1] == '\n')
+        {
+            pos += 2;
+        }
+        else if(pos < text.size() - 2 && text[pos + 1] == '\r' && text[pos + 2] == '\n')
+        {
+            pos += 3;
+        }
+        else
         {
-            result.replace(pos, paramTag.size() + 1, "    ");
+            ++pos;
+            continue;
+        }
+
+        //
+        // Erase any more CR/LF characters.
+        //
+        string::size_type next = text.find_first_not_of("\r\n", pos);
+        if(next != string::npos)
+        {
+            text.erase(pos, next - pos);
+        }
+    }
+
+    //
+    // Remove trailing whitespace.
+    //
+    pos = text.find_last_not_of(" \t\r\n");
+    if(pos != string::npos)
+    {
+        text.erase(pos + 1, text.size() - pos - 1);
+    }
 
-            if(first)
+    //
+    // Split text into lines.
+    //
+    StringVec lines;
+    if(!text.empty())
+    {
+        string::size_type start = 0;
+        while(start != string::npos)
+        {
+            string::size_type nl = text.find_first_of("\r\n", start);
+            string line;
+            if(nl != string::npos)
             {
-                string::size_type bol = result.rfind('\n', pos);
-                if(bol == string::npos)
-                {
-                    bol = 0;
-                }
-                else
+                line = text.substr(start, nl - start);
+                start = nl;
+            }
+            else
+            {
+                line = text.substr(start);
+                start = text.size();
+            }
+
+            lines.push_back(line);
+
+            start = text.find_first_not_of("\r\n", start);
+        }
+    }
+
+    return lines;
+}
+
+void
+Slice::Python::CodeVisitor::writeDocstring(const string& comment, const string& prefix)
+{
+    StringVec lines = stripMarkup(comment);
+    if(lines.empty())
+    {
+        return;
+    }
+
+    _out << nl << prefix << "\"\"\"";
+
+    for(StringVec::const_iterator q = lines.begin(); q != lines.end(); ++q)
+    {
+        if(q != lines.begin())
+        {
+            _out << nl;
+        }
+        _out << *q;
+    }
+
+    _out << "\"\"\"";
+}
+
+void
+Slice::Python::CodeVisitor::writeDocstring(const string& comment, const DataMemberList& members)
+{
+    StringVec lines = stripMarkup(comment);
+    if(lines.empty())
+    {
+        return;
+    }
+
+    _out << nl << "\"\"\"";
+
+    for(StringVec::const_iterator q = lines.begin(); q != lines.end(); ++q)
+    {
+        if(q != lines.begin())
+        {
+            _out << nl;
+        }
+        _out << *q;
+    }
+
+    if(!members.empty())
+    {
+        //
+        // Collect docstrings (if any) for the members.
+        //
+        map<string, StringVec> docs;
+        for(DataMemberList::const_iterator m = members.begin(); m != members.end(); ++m)
+        {
+            StringVec doc = stripMarkup((*m)->comment());
+            if(!doc.empty())
+            {
+                docs[(*m)->name()] = doc;
+            }
+        }
+        //
+        // Only emit members if there's a docstring for at least one member.
+        //
+        if(!docs.empty())
+        {
+            _out << nl << "Members:";
+            for(DataMemberList::const_iterator m = members.begin(); m != members.end(); ++m)
+            {
+                _out << nl << fixIdent((*m)->name()) << " -- ";
+                map<string, StringVec>::iterator p = docs.find((*m)->name());
+                if(p != docs.end())
                 {
-                    bol++;
+                    for(StringVec::const_iterator q = p->second.begin(); q != p->second.end(); ++q)
+                    {
+                        if(q != p->second.begin())
+                        {
+                            _out << nl;
+                        }
+                        _out << *q;
+                    }
                 }
-                result.insert(bol, "Arguments:\n");
-                first = false;
             }
         }
-    } while(pos != string::npos);
+    }
 
-    static const string returnTag = "@return";
-    pos = result.find(returnTag);
-    first = true;
-    if(pos != string::npos)
+    _out << "\"\"\"";
+}
+
+void
+Slice::Python::CodeVisitor::writeDocstring(const string& comment, const EnumeratorList& enums)
+{
+    StringVec lines = stripMarkup(comment);
+    if(lines.empty())
     {
-        result.replace(pos, returnTag.size() + 1, "    ");
-        string::size_type bol = result.rfind('\n', pos);
-        if(bol == string::npos)
+        return;
+    }
+
+    _out << nl << "\"\"\"";
+
+    for(StringVec::const_iterator q = lines.begin(); q != lines.end(); ++q)
+    {
+        if(q != lines.begin())
         {
-            bol = 0;
+            _out << nl;
         }
-        else
+        _out << *q;
+    }
+
+    if(!enums.empty())
+    {
+        //
+        // Collect docstrings (if any) for the enumerators.
+        //
+        map<string, StringVec> docs;
+        for(EnumeratorList::const_iterator e = enums.begin(); e != enums.end(); ++e)
+        {
+            StringVec doc = stripMarkup((*e)->comment());
+            if(!doc.empty())
+            {
+                docs[(*e)->name()] = doc;
+            }
+        }
+        //
+        // Only emit enumerators if there's a docstring for at least one enumerator.
+        //
+        if(!docs.empty())
         {
-            bol++;
+            _out << nl << "Enumerators:";
+            for(EnumeratorList::const_iterator e = enums.begin(); e != enums.end(); ++e)
+            {
+                _out << nl << fixIdent((*e)->name()) << " -- ";
+                map<string, StringVec>::iterator p = docs.find((*e)->name());
+                if(p != docs.end())
+                {
+                    for(StringVec::const_iterator q = p->second.begin(); q != p->second.end(); ++q)
+                    {
+                        if(q != p->second.begin())
+                        {
+                            _out << nl;
+                        }
+                        _out << *q;
+                    }
+                }
+            }
         }
-        result.insert(bol, "Returns:\n");
     }
 
-    static const string throwsTag = "@throws";
-    pos = 0;
-    first = true;
-    do
+    _out << "\"\"\"";
+}
+
+bool
+Slice::Python::CodeVisitor::parseOpComment(const string& comment, OpComment& c)
+{
+    //
+    // Remove most javadoc & HTML markup.
+    //
+    StringVec lines = stripMarkup(comment);
+    if(lines.empty())
     {
-        pos = result.find(throwsTag, pos);
-        if(pos != string::npos)
-        {
-            result.replace(pos, throwsTag.size() + 1, "    ");
+        return false;
+    }
+
+    //
+    // Extract the descriptions of parameters, exceptions and return values.
+    //
+    string name;
+    bool inParam = false, inException = false, inReturn = false;
+    vector<string>::size_type i = 0;
+    while(i < lines.size())
+    {
+        string l = lines[i];
+        string::size_type paramTag = l.find("@param");
+        string::size_type throwTag = l.find("@throw");
+        string::size_type returnTag = l.find("@return");
 
-            if(first)
+        if(paramTag != string::npos)
+        {
+            string::size_type pos = l.find_first_of(" \t", paramTag);
+            if(pos != string::npos)
+            {
+                pos = l.find_first_not_of(" \t", pos);
+            }
+            if(pos != string::npos)
             {
-                string::size_type bol = result.rfind('\n', pos);
-                if(bol == string::npos)
+                string::size_type namePos = pos;
+                pos = l.find_first_of(" \t", pos);
+                inParam = true;
+                inException = false;
+                inReturn = false;
+                if(pos == string::npos)
                 {
-                    bol = 0;
+                    //
+                    // Doc assumed to have the format
+                    //
+                    // @param foo
+                    // Description of foo...
+                    //
+                    name = l.substr(namePos);
+                    c.params[name] = "";
                 }
                 else
                 {
-                    bol++;
+                    name = l.substr(namePos, pos - namePos);
+                    pos = l.find_first_not_of(" \t", pos);
+                    if(pos != string::npos)
+                    {
+                        c.params[name] = l.substr(pos);
+                    }
+                    else
+                    {
+                        c.params[name] = "";
+                    }
+                }
+            }
+            lines.erase(lines.begin() + i);
+            continue;
+        }
+        else if(throwTag != string::npos)
+        {
+            string::size_type pos = l.find_first_of(" \t", throwTag);
+            if(pos != string::npos)
+            {
+                pos = l.find_first_not_of(" \t", pos);
+            }
+            if(pos != string::npos)
+            {
+                string::size_type namePos = pos;
+                pos = l.find_first_of(" \t", pos);
+                inException = true;
+                inParam = false;
+                inReturn = false;
+                if(pos == string::npos)
+                {
+                    //
+                    // Doc assumed to have the format
+                    //
+                    // @throw foo
+                    // Description of foo...
+                    //
+                    name = l.substr(namePos);
+                    c.exceptions[name] = "";
+                }
+                else
+                {
+                    name = l.substr(namePos, pos - namePos);
+                    pos = l.find_first_not_of(" \t", pos);
+                    if(pos != string::npos)
+                    {
+                        c.exceptions[name] = l.substr(pos);
+                    }
+                    else
+                    {
+                        c.exceptions[name] = "";
+                    }
+                }
+            }
+            lines.erase(lines.begin() + i);
+            continue;
+        }
+        else if(returnTag != string::npos)
+        {
+            string::size_type pos = l.find_first_of(" \t", returnTag);
+            if(pos != string::npos)
+            {
+                pos = l.find_first_not_of(" \t", pos);
+            }
+            if(pos != string::npos)
+            {
+                inReturn = true;
+                inException = false;
+                inParam = false;
+                c.returns = l.substr(pos);
+            }
+            lines.erase(lines.begin() + i);
+            continue;
+        }
+        else
+        {
+            //
+            // We didn't find a tag so we assume this line is a continuation of a
+            // previous description.
+            //
+            string::size_type pos = l.find_first_not_of(" \t");
+            if(pos != string::npos && l[pos] != '@')
+            {
+                if(inParam)
+                {
+                    assert(!name.empty());
+                    if(!c.params[name].empty())
+                    {
+                        c.params[name] += " ";
+                    }
+                    c.params[name] += l.substr(pos);
+                    lines.erase(lines.begin() + i);
+                    continue;
+                }
+                else if(inException)
+                {
+                    assert(!name.empty());
+                    if(!c.exceptions[name].empty())
+                    {
+                        c.exceptions[name] += " ";
+                    }
+                    c.exceptions[name] += l.substr(pos);
+                    lines.erase(lines.begin() + i);
+                    continue;
+                }
+                else if(inReturn)
+                {
+                    if(!c.returns.empty())
+                    {
+                        c.returns += " ";
+                    }
+                    c.returns += l.substr(pos);
+                    lines.erase(lines.begin() + i);
+                    continue;
                 }
-                result.insert(bol, "Exceptions:\n");
-                first = false;
             }
         }
-    } while(pos != string::npos);
+
+        i++;
+    }
 
     //
-    // Escape triple quotes.
+    // All remaining lines become the general description.
     //
-    static const string quotes = "'''";
-    pos = 0;
-    do
+    for(vector<string>::iterator p = lines.begin(); p != lines.end(); ++p)
     {
-        pos = result.find(quotes, pos);
-        if(pos != string::npos)
+        if(p->find_first_not_of(" \t\n\r") != string::npos)
         {
-            result.insert(pos, "\\");
-            pos += quotes.size() + 1;
+            c.description.push_back(*p);
         }
-    } while(pos != string::npos);
+    }
+
+    return true;
+}
+
+void
+Slice::Python::CodeVisitor::writeDocstring(const OperationPtr& op, DocstringMode mode, bool local)
+{
+    OpComment comment;
+    if(!parseOpComment(op->comment(), comment))
+    {
+        return;
+    }
+
+    TypePtr ret = op->returnType();
+    ParamDeclList params = op->parameters();
+    vector<string> inParams, outParams;
+    for(ParamDeclList::iterator p = params.begin(); p != params.end(); ++p)
+    {
+        if((*p)->isOutParam())
+        {
+            outParams.push_back((*p)->name());
+        }
+        else
+        {
+            inParams.push_back((*p)->name());
+        }
+    }
+
+    if(comment.description.empty())
+    {
+        if((mode == DocSync || mode == DocDispatch) && comment.params.empty() && comment.exceptions.empty() &&
+           comment.returns.empty())
+        {
+            return;
+        }
+        else if(mode == DocAsyncBegin && inParams.empty())
+        {
+            return;
+        }
+        else if(mode == DocAsyncEnd && outParams.empty() && comment.returns.empty())
+        {
+            return;
+        }
+        else if(mode == DocAsyncDispatch && inParams.empty() && comment.exceptions.empty())
+        {
+            return;
+        }
+    }
 
     //
-    // Fold multiple empty lines.
+    // Emit the general description.
     //
-    pos = 0;
-    while(true)
+    _out << nl << "\"\"\"";
+    if(!comment.description.empty())
     {
-        pos = result.find('\n', pos);
-        if(pos == string::npos)
+        for(StringVec::const_iterator q = comment.description.begin(); q != comment.description.end(); ++q)
         {
-            break;
+            if(q != comment.description.begin())
+            {
+                _out << nl;
+            }
+            _out << *q;
         }
+    }
 
-        //
-        // Skip the next LF or CR/LF, if present.
-        //
-        if(pos < result.size() - 1 && result[pos + 1] == '\n')
+    //
+    // Emit arguments.
+    //
+    bool needArgs = false;
+    switch(mode)
+    {
+    case DocSync:
+    case DocAsyncBegin:
+    case DocDispatch:
+        needArgs = !local || !inParams.empty();
+        break;
+    case DocAsyncEnd:
+    case DocAsyncDispatch:
+        needArgs = true;
+        break;
+    }
+
+    if(needArgs)
+    {
+        _out << nl << "Arguments:";
+        if(mode == DocAsyncDispatch)
         {
-            pos += 2;
+            _out << nl << "_cb -- The asynchronous callback object.";
         }
-        else if(pos < result.size() - 2 && result[pos + 1] == '\r' && result[pos + 2] == '\n')
+        for(vector<string>::iterator q = inParams.begin(); q != inParams.end(); ++q)
         {
-            pos += 3;
+            string fixed = fixIdent(*q);
+            _out << nl << fixed << " -- ";
+            StringMap::const_iterator r = comment.params.find(*q);
+            if(r == comment.params.end())
+            {
+                r = comment.params.find(fixed); // Just in case.
+            }
+            if(r != comment.params.end())
+            {
+                _out << r->second;
+            }
         }
-        else
+        if(mode == DocAsyncBegin)
         {
-            ++pos;
-            continue;
+            _out << nl << "_response -- The asynchronous response callback."
+                 << nl << "_ex -- The asynchronous exception callback."
+                 << nl << "_sent -- The asynchronous sent callback.";
         }
-
-        //
-        // Erase any more CR/LF characters.
-        //
-        string::size_type next = result.find_first_not_of("\r\n", pos);
-        if(next != string::npos)
+        if(!local && (mode == DocSync || mode == DocAsyncBegin))
         {
-            result.erase(pos, next - pos);
+            _out << nl << "_ctx -- The request context for the invocation.";
         }
+        if(!local && (mode == DocDispatch || mode == DocAsyncDispatch))
+        {
+            _out << nl << "current -- The Current object for the invocation.";
+        }
+    }
+    else if(mode == DocAsyncEnd)
+    {
+        _out << nl << "Arguments:"
+             << nl << "_r - The asynchronous result object for the invocation.";
     }
 
     //
-    // Remove trailing whitespace.
+    // Emit return value(s).
     //
-    pos = result.find_last_not_of(" \t\r\n");
-    if(pos != string::npos)
+    if(mode == DocAsyncBegin)
     {
-        result.erase(pos + 1, result.size() - pos - 1);
+        _out << nl << "Returns: An asynchronous result object for the invocation.";
     }
 
-    return result;
+    if((mode == DocSync || mode == DocAsyncEnd || mode == DocDispatch) && (ret || !outParams.empty()))
+    {
+        if((outParams.size() + (ret ? 1 : 0)) > 1)
+        {
+            _out << nl << "Returns a tuple containing the following:";
+            if(ret)
+            {
+                _out << nl << "_retval -- " << comment.returns;
+            }
+            for(vector<string>::iterator q = outParams.begin(); q != outParams.end(); ++q)
+            {
+                string fixed = fixIdent(*q);
+                _out << nl << fixed << " -- ";
+                StringMap::const_iterator r = comment.params.find(*q);
+                if(r == comment.params.end())
+                {
+                    r = comment.params.find(fixed); // Just in case.
+                }
+                if(r != comment.params.end())
+                {
+                    _out << r->second;
+                }
+            }
+        }
+        else if(ret && !comment.returns.empty())
+        {
+            _out << nl << "Returns: " << comment.returns;
+        }
+        else if(!outParams.empty())
+        {
+            assert(outParams.size() == 1);
+            _out << nl << "Returns:";
+            string fixed = fixIdent(outParams[0]);
+            _out << nl << fixed << " -- ";
+            StringMap::const_iterator r = comment.params.find(outParams[0]);
+            if(r == comment.params.end())
+            {
+                r = comment.params.find(fixed); // Just in case.
+            }
+            if(r != comment.params.end())
+            {
+                _out << r->second;
+            }
+        }
+    }
+
+    //
+    // Emit exceptions.
+    //
+    if((mode == DocSync || mode == DocAsyncEnd || mode == DocDispatch || mode == DocAsyncDispatch) &&
+       !comment.exceptions.empty())
+    {
+        _out << nl << "Throws:";
+        for(StringMap::const_iterator r = comment.exceptions.begin(); r != comment.exceptions.end(); ++r)
+        {
+            _out << nl << r->first << " -- " << r->second;
+        }
+    }
+    _out << "\"\"\"";
 }
 
 void
@@ -2416,7 +2945,7 @@ Slice::Python::printHeader(IceUtilInternal::Output& out)
     static const char* header =
 "# **********************************************************************\n"
 "#\n"
-"# Copyright (c) 2003-2015 ZeroC, Inc. All rights reserved.\n"
+"# Copyright (c) 2003-2016 ZeroC, Inc. All rights reserved.\n"
 "#\n"
 "# This copy of Ice is licensed to you under the terms described in the\n"
 "# ICE_LICENSE file included in this distribution.\n"