improved comment formatting for Python

Examples/test-suite/python/commentVerifier.py

@@ -0,0 +1,24 @@
+
+def check(got, expected):
+  #if got is Null
+  #  raise RuntimeError('Expected comment string\n')
+  #gotStr = string.replace(got, ' ', '')
+  #gotStr = string.replace(gotStr, '\n', '')
+  # gotStr = string.replace(gotStr, '\t', '')
+  #expectedStr = string.replace(expected, ' ', '')
+  #expectedStr = string.replace(expectedStr, '\n', '')
+  #expectedStr = string.replace(expectedStr, '\t', '')
+  if not got == expected:
+    print "\n\n////////////////////////////////////////////////////////////////////////"
+    expectedFileName = "expected.txt"
+    gotFileName = "got.txt"
+    print "Output is also saved to files '" + expectedFileName + \
+                                   "' and '" + gotFileName + "'";
+
+    expectedFile = open(expectedFileName, "w")
+    expectedFile.write(expected)
+    expectedFile.close()
+    gotFile = open(gotFileName, "w")
+    gotFile.write(got)
+    gotFile.close()    
+    raise RuntimeError("Expected: [" + str(expected) + "]\n" + "Got     : [" + str(got) + "]\n")

Examples/test-suite/python/doxygen_basic_translate_runme.py

@@ -3,71 +3,77 @@
 import doxygen_basic_translate
 import string
 import sys
+import commentVerifier
 
-def check(got, expected):
-  #if got is Null
-  #  raise RuntimeError('Expected comment string\n')
-  gotStr = string.replace(got, ' ', '')
-  gotStr = string.replace(gotStr, '\n', '')
-  gotStr = string.replace(gotStr, '\t', '')
-  expectedStr = string.replace(expected, ' ', '')
-  expectedStr = string.replace(expectedStr, '\n', '')
-  expectedStr = string.replace(expectedStr, '\t', '')
-  if not gotStr == expectedStr:
-    raise RuntimeError("Expected: [" + str(expected) + "]\n" + "Got     : [" + str(got) + "]\n")
+commentVerifier.check(doxygen_basic_translate.function.__doc__,
+  """
+  Brief description.
 
-check(doxygen_basic_translate.function.__doc__, ''
-'  Brief description.\n'
-'  The comment text\n'
-'  Authors:\n'
-'  Some author\n'
-'  Return:\n'
-'  Some number\n'
-'  See also:\n'
-'  function2\n'
+  The comment text.
+
+  Author: Some author
+
+  Return: Some number
+
+  See also: function2
+  """
 )
-check(doxygen_basic_translate.function2.__doc__, ''
-'  A test of a very very very very very very very very very very very'
-'  very very very very very'
-'  very very very very very long comment'
-'  string.'
+commentVerifier.check(doxygen_basic_translate.function2.__doc__,
+  """
+  A test of a very very very very very very very very very very very very very very very very
+  very very very very very long comment string.
+  """
 )
-check(doxygen_basic_translate.function3.__doc__, ''
-'  ----------------------------------------------------------------\n'
-'  Overload 1:\n'
-'  ----------------------------------------------------------------\n'
-'  A test for overloaded functions\n'
-'  This is function __one__\n'
-'  ----------------------------------------------------------------\n'
-'  Overload 2:\n'
-'  ----------------------------------------------------------------\n'
-'  A test for overloaded functions\n'
-'  This is function __two__\n'
+commentVerifier.check(doxygen_basic_translate.function3.__doc__,
+  """
+  ----------------------------------------------------------------
+  Overload 1:
+  ----------------------------------------------------------------
+  A test for overloaded functions
+  This is function __one__
+
+  ----------------------------------------------------------------
+  Overload 2:
+  ----------------------------------------------------------------
+  A test for overloaded functions
+  This is function __two__
+
+  """
 )
-check(doxygen_basic_translate.function4.__doc__, ''
-'  A test of some mixed tag usage\n' 
-'  If: CONDITION {\n'
-'  This _code_fragment shows us something .\n'
-'  Title: Minuses:\n'
-'   -it\'s senseless\n'
-'   -it\'s stupid\n'
-'   -it\'s null\n'
-'  Warning:\n'
-'  This may not work as expected\n'
-'  int main() { while(true); }\n'
-'  }'
+commentVerifier.check(doxygen_basic_translate.function4.__doc__,
+  """
+  A test of some mixed tag usage
+  If: CONDITION {
+  This _code_ fragment shows us something .
+  Title: Minuses:
+   -it\'s senseless
+   -it\'s stupid
+   -it\'s null
+
+  Warning: This may not work as expected
+
+  int main() { while(true); }
+
+  }
+  """
 )
-check(doxygen_basic_translate.function5.__doc__, ''
-'  This is a post comment. \n'
+commentVerifier.check(doxygen_basic_translate.function5.__doc__,
+  """
+  This is a post comment. 
+  """
 )
-check(doxygen_basic_translate.function6.__doc__, ''
-'  Test for default args \n'
-'  Arguments: \n'
-'  a (int) -- Some parameter, default is 42\n'
+commentVerifier.check(doxygen_basic_translate.function6.__doc__,
+  """
+  Test for default args
+  Arguments:
+    a (int) -- Some parameter, default is 42
+  """
 )
-check(doxygen_basic_translate.function7.__doc__, ''
-' Test for a parameter with difficult type \n'
-'  (mostly for python) \n'
-'  Arguments: \n'
-'  a (Shape::superType *[10])                              -- Very strange param \n'
+commentVerifier.check(doxygen_basic_translate.function7.__doc__,
+  """
+  Test for a parameter with difficult type
+  (mostly for python)
+  Arguments:
+    a (Shape::superType *[10]) -- Very strange param
+  """
 )

Examples/test-suite/python/doxygen_misc_constructs_runme.py

@@ -1,54 +1,48 @@
 #!/usr/bin/python
 
-import doxygen_tricky_constructs
+import doxygen_misc_constructs
 import string
 import sys
+import commentVerifier
 
-def check(got, expected):
-  #if got is Null
-  #  raise RuntimeError('Expected comment string\n')
-  gotStr = string.replace(got, ' ', '')
-  gotStr = string.replace(gotStr, '\n', '')
-  gotStr = string.replace(gotStr, '\t', '')
-  expectedStr = string.replace(expected, ' ', '')
-  expectedStr = string.replace(expectedStr, '\n', '')
-  expectedStr = string.replace(expectedStr, '\t', '')
-  if not gotStr == expectedStr:
-    raise RuntimeError("Expected: [" + str(expected) + "]\n" + "Got     : [" + str(got) + "]\n")
 
-check(doxygen_tricky_constructs.getAddress.__doc__, ''
-'Returns address of file line.'
-''
-'   Arguments:'
-'  fileName (int &)                              -- name of the file, where the source'
-'                                line is located'
-'  line (int)                              -- line number'
-'  isGetSize (bool)                              -- if set, for every object location'
-'                                both address and size are returned'
-''
-''
-'  Connection::getId() <br>'
+commentVerifier.check(doxygen_misc_constructs.getAddress.__doc__,
+  r"""
+  Returns address of file line.
+
+  Arguments:
+    fileName (int &) -- name of the file, where the source line is located
+    line (int) -- line number
+    isGetSize (bool) -- if set, for every object location both address and size are returned
+
+  Connection::getId() 
+  """)
+
+commentVerifier.check(doxygen_misc_constructs.CConnectionConfig.__doc__,
+    r"""
+    This class contains information for connection to winIDEA. Its methods 
+    return reference to self, so we can use it like this:
+
+    CConnectionConfig config = new CConnectionConfig();
+    config.discoveryPort(5534).dllPath("C:\\myWinIDEA\\connect.dll").id("main");
+
+
+    All parameters are optional. Set only what is required, default values are
+    used for unspecified parameters.
+
+
+    advancedWinIDEALaunching.py Python example. 
+    """)
+
+commentVerifier.check(doxygen_misc_constructs.waitTime.__doc__,
+  r"""
+  Determines how long the 'isystem.connect' should wait for running 
+  instances to respond. Only one of 'lfWaitXXX' flags from IConnect::ELaunchFlags
+  may be specified.
+  """
 )
-check(doxygen_tricky_constructs.CConnectionConfig.__doc__, ''
-'    This class contains information for connection to winIDEA. Its methods'
-'    return reference to self, so we can use it like this:'
-'    <pre>'
-'    CConnectionConfig config = new CConnectionConfig();'
-'    config.discoveryPort(5534).dllPath("C: \yWinIDEA \onnect.dll").id("main");'
-'    </pre>'
-''
-'     All parameters are optional. Set only what is required, default values are'
-'    used for unspecified parameters.'
-'    <p>'
-''
-'     advancedWinIDEALaunching.py Python example. <br>'
-''
+commentVerifier.check(doxygen_misc_constructs.getConnection.__doc__,
+  r"""
+  This function returns connection id.
+  """
 )
-check(doxygen_tricky_constructs.waitTime.__doc__, ''
-'  Determines how long the isystem.connect should wait for running'
-'  instances to respond. Only one of lfWaitXXX flags from IConnect::ELaunchFlags'
-'  may be specified.'
-)
-check(doxygen_tricky_constructs.getConnection.__doc__, ''
-'This class manages connection.'
-)