Improve Python docstring indentation handling

SWIG-3.0.5 and earlier sometimes truncated text provided in the docstring
feature.
SWIG-3.0.6 gave a 'Line indented less than expected' error instead of
truncating the docstring text.
Now the indentation for the 'docstring' feature is smarter and is
adjusted so that no truncation occurs.

Closes #475

3 files changed, 199 insertions, 0 deletions

diff --git a/Examples/test-suite/python/Makefile.in b/Examples/test-suite/python/Makefile.in
index a99c30439..59c8eed9e 100644
--- a/Examples/test-suite/python/Makefile.in
+++ b/Examples/test-suite/python/Makefile.in
@@ -59,6 +59,7 @@ CPP_TEST_CASES += \
 	python_abstractbase \
 	python_append \
 	python_director \
+	python_docstring \
 	python_nondynamic \
 	python_overload_simple_cast \
 	python_pythoncode \
diff --git a/Examples/test-suite/python/python_docstring_runme.py b/Examples/test-suite/python/python_docstring_runme.py
new file mode 100644
index 000000000..0284ea0de
--- /dev/null
+++ b/Examples/test-suite/python/python_docstring_runme.py
@@ -0,0 +1,100 @@
+from python_docstring import *
+import inspect
+
+def check(got, expected):
+    expected_list = expected.split("\n")
+    got_list = got.split("\n")
+
+    if expected_list != got_list:
+        raise RuntimeError("\n" + "Expected: " + str(expected_list) + "\n" + "Got     : " + str(got_list))
+
+# When getting docstrings, use inspect.getdoc(x) instead of x.__doc__ otherwise the different options
+# such as -O, -builtin, -classic produce different initial indentation.
+
+check(inspect.getdoc(DocStrings.docstring1),
+    "  line 1\n"
+    "line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring2),
+    "line 1\n"
+    "  line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "  line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring3),
+    "line 1\n"
+    "  line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "  line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring4),
+    "line 1\n"
+    "  line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "  line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring5),
+    "line 1\n"
+    "  line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "  line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring6),
+    "line 1\n"
+    "  line 2\n"
+    "\n"
+    "\n"
+    "\n"
+    "  line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstring7),
+    "line 1\n"
+    "line 2\n"
+    "line 3"
+    )
+
+check(inspect.getdoc(DocStrings.docstringA),
+    "first line\n"
+    "second line"
+    )
+
+check(inspect.getdoc(DocStrings.docstringB),
+    "first line\n"
+    "second line"
+    )
+
+check(inspect.getdoc(DocStrings.docstringC),
+    "first line\n"
+    "second line"
+    )
+
+# One line doc special case, use __doc__
+check(DocStrings.docstringX.__doc__,
+    "  one line docs"
+    )
+
+check(inspect.getdoc(DocStrings.docstringX),
+    "one line docs"
+    )
+
+check(inspect.getdoc(DocStrings.docstringY),
+    "one line docs"
+    )
diff --git a/Examples/test-suite/python_docstring.i b/Examples/test-suite/python_docstring.i
new file mode 100644
index 000000000..3b88167eb
--- /dev/null
+++ b/Examples/test-suite/python_docstring.i
@@ -0,0 +1,98 @@
+%module python_docstring
+
+// Test indentation when using the docstring feature.
+// Checks tabs and spaces as input for indentation.
+
+%feature("docstring") docstring1 %{
+  line 1
+line 2
+
+  
+    
+line 3
+%}
+
+%feature("docstring") docstring2 %{
+line 1
+  line 2
+  
+      
+    
+  line 3
+  %}
+
+%feature("docstring") docstring3 %{
+    line 1
+      line 2
+
+          
+        
+      line 3
+      %}
+
+%feature("docstring") docstring4 %{
+	line 1
+	  line 2
+	
+	      
+	    
+	  line 3
+	  %}
+
+%feature("docstring") docstring5
+%{	line 1
+	  line 2
+	
+	      
+	    
+	  line 3
+	  %}
+
+%feature("docstring") docstring6
+{
+	line 1
+	  line 2
+	
+	      
+	    
+	  line 3
+}
+
+%feature("docstring") docstring7
+{
+line 1
+line 2
+line 3
+}
+
+%feature("docstring") docstringA
+%{    first line
+    second line%}
+
+%feature("docstring") docstringB
+%{		first line
+		second line%}
+
+%feature("docstring") docstringC
+%{  first line
+  second line%}
+
+%feature("docstring") docstringX "  one line docs"
+%feature("docstring") docstringY "one line docs"
+
+%inline %{
+struct DocStrings {
+  void docstring1() {}
+  void docstring2() {}
+  void docstring3() {}
+  void docstring4() {}
+  void docstring5() {}
+  void docstring6() {}
+  void docstring7() {}
+  void docstringA() {}
+  void docstringB() {}
+  void docstringC() {}
+  void docstringX() {}
+  void docstringY() {}
+};
+%}