Fixed lots of PyDoc converter problems, see doxygen_tricky_constructs test

git-svn-id: https://swig.svn.sourceforge.net/svnroot/swig/branches/gsoc2012-doxygen@13633 626c5289-ae23-0410-ae9c-e8d60b6d4f22

Examples/test-suite/doxygen_tricky_constructs.i

@@ -0,0 +1,106 @@
+# This file contains tests for situations, which do not normally
+# appear in the code, but must neverthless be handled correctly.
+
+%module doxygen_tricky_constructs
+
+%inline %{
+
+    # Bug 1: Tag '@endink' is not recognized becuse it is not
+    # followed by whitespace.
+
+    /** 
+     * Tag endlink must be recognized also when followed by nonspace charater.
+     *
+     * @link Connection::getId() @endlink<br>
+     */
+    char g_counter;
+
+
+    /** 
+     * Tag endlink must be recognized also when it is the last token
+     * in the commment.
+     *
+     * @link Connection::getId() @endlink<br>
+     * @link debugIdeTraceProfilerCoverageSample.py Python example. @endlink
+     */
+    int g_zipCode;
+
+
+    # Bug 2: Paramter 'isReportSize' is missing in comment of the overload, which
+    # has it. This bug disappears if @endlink is follwed by a space.
+    #
+    # Bug 3: Empty line before the link is missing,
+    # making the link text part of parameter description. This bug appears also
+    # when there is ordinary text in place of the link in case of overload
+    # with only 2 parameters.
+    /**
+     * Returns address of file line.
+     *
+     * @param fileName name of the file, where the source line is located
+     * @param line line number
+     * @param isGetSize if set, for every object location both address and size are returned
+     *
+     * @link Connection::getId() @endlink <br>
+     */
+    std::vector<DWORD> getAddress(const std::string &fileName, 
+                                  int line, 
+                                  bool isGetSize = false);
+
+    # Bug 4: The first comment is attached to the second in Python (wrong),
+    # but not in Java (correct).
+    /** 
+     * \defgroup icFacade isystem.connect Facade
+     *
+     * This page shows the core classes, which can be used to control
+     * all aspects of winIDEA, for example: debugging, analyzers, IO module, ...
+     */
+
+    /** 
+     * 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:\\myWinIDEA\\connect.dll").id("main");
+     * </pre>
+     *
+     * All parameters are optional. Set only what is required, default values are
+     * used for unspecified parameters.
+     * <p>
+     *
+     * @link advancedWinIDEALaunching.py Python example. @endlink <br>
+     */
+    class CConnectionConfig
+    {
+    };
+
+    # Bug 5: Text after '\c' has no space following in Python.
+    # There are also to many empty lines in multiline comments in Python.
+    # Whitespaces are really a problem in Python (space and newlines),
+    # I like a parameter type added to each parameter description!
+    #    """
+    #    Determines how long the isystem.connectshould wait for running 
+    #
+    #    instances to respond. Only one of lfWaitXXXflags from IConnect::ELaunchFlags 
+    #
+    #    may be specified. 
+    #
+    #    """
+
+    /**
+     * Determines how long the \c isystem.connect should wait for running 
+     * instances to respond. Only one of \c lfWaitXXX flags from IConnect::ELaunchFlags
+     * may be specified.
+     */
+    int waitTime(long waitTime);
+
+
+    # Bug 6: Text after tag \ingroup appears in Python comment (empty line in
+    # Java, which is acceptable):
+    /** \ingroup icFacade
+     *
+     * This class manages connection.
+     */
+    int getConnection();
+    
+    
+%}

Examples/test-suite/python/doxygen_translate_all_tags_runme.py

@@ -19,12 +19,6 @@ def check(got, expected):
 check(doxygen_translate_all_tags.function.__doc__, ''
 '  _Hello_'
 ''
-'  SomeLatexIndex '
-''
-'  someGroup"Some title" '
-''
-'  theAnchor'
-''
 '   -some list item '
 ''
 '  This is attention! '
@@ -44,60 +38,29 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 ''
 '  codeword'
 ''
-'  someCategoryheaderFile.hheaderName'
-''
 '  \'citationword\''
 ''
-'  someClassheaderFile.hheaderName'
-''
 '  some test code '
 ''
 '  Conditional comment: SOMECONDITION'
 '  Some conditional comment '
 '  End of conditional comment.'
 ''
-'  someClass::someMethod'
-''
-'  someClass::someMethod2'
-''
-'  someClass::someMethod3'
-''
 '  Copyright:'
 '  some copyright '
 ''
 '  1970 - 2012 '
 ''
-'  someDefine'
-''
-'  someGroupSome titles '
-''
 '  Deprecated:'
 '  Now use another function '
 ''
 '  This is very large '
 '  and detailed description of some thing '
 ''
-'  /somePath/someFolder'
-''
-'  someFile.h'
-''
-'  digraph example { '
-'  node [shape=record, fontname=Helvetica, fontsize=10]; '
-''
-'  b [ label="class B" URL=" B"]; '
-'  c [ label="class C" URL=" C"]; '
-'  b -> c [ arrowhead="open", style="dashed" ]; '
-'  } '
-''
-''
-'  dotFile.dotThe caption'
-''
 '  _italicword_'
 ''
 '  emphazedWord'
 ''
-'  someEnum'
-''
 '  Example:'
 '  someFile.txt'
 '  Some details on using the example '
@@ -105,16 +68,6 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 '  Throws:'
 '  SuperError'
 ''
-'  someOtherFunction'
-''
-'  file.h'
-''
-'  someFn '
-''
-'  someHeader.hHeader name'
-''
-'  htmlFile.htm'
-''
 '  This will only appear in hmtl '
 ''
 '  If: ANOTHERCONDITION {'
@@ -135,21 +88,11 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 '  This is printed if not '
 '  }'
 ''
-'  Image: htmltestImage.bmpHello, world!asd=10qwe'
-''
-'  someFunction'
-''
-'  header.h'
-''
-'  header2.h'
-''
-'  someGroupanotherGroup'
+'  Image: testImage.bmp(Hello, world!)'
 ''
 '  Some text '
 '  describing invariant. '
 ''
-'  someInterfacesomeHeader.hHeader name'
-''
 '  This will only appear in LATeX '
 ''
 '  <ul> '
@@ -160,28 +103,10 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 ''
 '  </ul> '
 ''
-'  example '
-''
 '  someMember Some description follows '
 ''
-'  Sometitle '
-''
 '  This will only appear in man '
 ''
-'  someThing'
-''
-'  Sender,Receiver; '
-'  Sender->Receiver [label="Command()", URL=" '
-'  Receiver::Command()"]; '
-'  Sender<-Receiver [label="Ack()", URL=" '
-'  Ack()", ID="1"]; '
-''
-'  mscFile.mscThe caption'
-''
-'  someHeader.h '
-''
-'  someNamespace'
-''
 '  Notes:'
 '  Here '
 '  is the note! '
@@ -191,37 +116,13 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 ''
 '  someword'
 ''
-'  superPackage'
-''
-'  somePageThe title '
-''
 '  Title: The paragraph title '
 '  The paragraph text. '
 '  Maybe even multiline '
 ''
-'  someParagraphParagraph title '
-''
 '  Arguments:'
 '  a (int)                              -- the first param '
 ''
-'  Some description '
-''
-'  Some description '
-''
-'  someVar '
-''
-'  someProtocolheader.hHeader name'
-''
-'  someAnchor'
-''
-'  toSomething'
-''
-'  toSomethingElse'
-''
-'  someName'
-''
-'  someName'
-''
 '  Remarks:'
 '  Some remark text '
 ''
@@ -234,47 +135,20 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 ''
 '  may return '
 ''
-'  someValueSome description '
-''
-''
 '  This will only appear in RTF '
 ''
 ''
 '  See also:'
 '  someOtherMethod '
 ''
-'  someSectionSome title '
-''
 '  function '
 ''
 '  Same as '
 '  brief description '
 ''
-''
-''
 '  Since:'
 '  version 0.0.0.1 '
 ''
-'  somePattern '
-''
-'  someLine '
-''
-'  example.hSome snippet '
-''
-'  someStruct'
-''
-'  someSubpageSome description'
-''
-'  someSubsectionSome title '
-''
-'  someSubsectionSome title '
-''
-''
-''
-'  Some '
-'  description of the '
-'  test case '
-''
 '  Throws:'
 '  superException'
 ''
@@ -286,34 +160,17 @@ check(doxygen_translate_all_tags.function.__doc__, ''
 '  Arguments:'
 '  b (float)                              -- B is mentioned again... '
 ''
-'  someTypedef '
-''
-'  someUnion'
-''
-'  somePattern '
-''
-'  someVar '
-''
-''
 '  very long '
 '  text with tags <sometag> '
 ''
-''
-'  someFile.h'
-''
 '  Version:'
 '  0.0.0.2 '
 ''
 '  Warning:'
 '  This is senseless! '
 ''
-'  someGroupSome title '
-''
-''
 '  This will only appear in XML '
 ''
-'  todo"Todo"Todo List'
-''
 '  Here goes test of symbols: '
 '  $@\&~<>#%".::'
 ''

Examples/test-suite/python/doxygen_translate_runme.py

@@ -71,7 +71,7 @@ check(doxygen_translate.function.__doc__, ''
 '  This is printed if not '
 '  }'
 ''
-'  Image: htmltestImage.bmpHello, world!asd=10qwe'
+'  Image: testImage.bmp(Hello, world!)'
 ''
 '  <ul> '
 ''
@@ -92,7 +92,7 @@ check(doxygen_translate.function.__doc__, ''
 ''
 '  someword'
 ''
-'  superPackage'
+''
 ''
 '  Title: The paragraph title '
 '  The paragraph text. '
@@ -145,4 +145,4 @@ check(doxygen_translate.function.__doc__, ''
 '  $@\&~<>#%".::'
 ''
 '  And here goes simple text '
-)
+)

Source/DoxygenTranslator/src/PyDocConverter.cpp

@@ -68,6 +68,46 @@ void PyDocConverter::fillStaticTables() {
   tagHandlers["\""] = make_pair(&PyDocConverter::handleTagChar, "");
   tagHandlers["."] = make_pair(&PyDocConverter::handleTagChar, "");
   tagHandlers["::"] = make_pair(&PyDocConverter::handleTagChar, "");
+  // these commands are stripped out, and only their content is printed
+  tagHandlers["attention"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["author"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["authors"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["brief"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["bug"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["c"] = make_pair(&PyDocConverter::handleParagraph, " ");
+  tagHandlers["code"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["copyright"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["date"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["deprecated"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["details"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["em"] = make_pair(&PyDocConverter::handleParagraph, " ");
+  tagHandlers["example"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["exception"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["htmlonly"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["invariant"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["latexonly"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["link"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["manonly"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["note"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["p"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["partofdescription"] = make_pair(&PyDocConverter::handleParagraph, " ");
+  tagHandlers["rtfonly"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["return"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["returns"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["result"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["remark"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["remarks"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["sa"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["see"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["since"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["short"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["throw"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["throws"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["todo"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["version"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["verbatim"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["warning"] = make_pair(&PyDocConverter::handleParagraph, "");
+  tagHandlers["xmlonly"] = make_pair(&PyDocConverter::handleParagraph, "");
   // these commands have special handlers
   tagHandlers["arg"] = make_pair(&PyDocConverter::handleTagMessage, " -");
   tagHandlers["cond"] = make_pair(&PyDocConverter::handleTagMessage, "Conditional comment: ");
@@ -76,7 +116,7 @@ void PyDocConverter::fillStaticTables() {
   tagHandlers["endcond"] = make_pair(&PyDocConverter::handleTagMessage, "End of conditional comment.");
   tagHandlers["if"] = make_pair(&PyDocConverter::handleTagIf, "If: ");
   tagHandlers["ifnot"] = make_pair(&PyDocConverter::handleTagIf, "If not: ");
-  tagHandlers["image"] = make_pair(&PyDocConverter::handleTagMessage, "Image: ");
+  tagHandlers["image"] = make_pair(&PyDocConverter::handleTagImage, "");
   tagHandlers["li"] = make_pair(&PyDocConverter::handleTagMessage, " -");
   tagHandlers["overload"] = make_pair(&PyDocConverter::handleTagMessage, "This is an overloaded member function, provided for"
       " convenience.\nIt differs from the above function only in what"
@@ -165,17 +205,14 @@ std::string PyDocConverter::translateSubtree(DoxygenEntity & doxygenEntity) {
 
 void PyDocConverter::translateEntity(DoxygenEntity & doxyEntity, std::string &translatedComment) {
   // check if we have needed handler and call it
-  std::string dummy;
   std::map<std::string, std::pair<tagHandler, std::string > >::iterator it;
   it = tagHandlers.find(doxyEntity.typeOfEntity);
   if (it!=tagHandlers.end())
     (this->*(it->second.first))(doxyEntity, translatedComment, it->second.second);
-  else
-    handleParagraph(doxyEntity, translatedComment, dummy);
 }
 
-void PyDocConverter::handleParagraph(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
-  translatedComment += justifyString(translateSubtree(tag), 0);
+void PyDocConverter::handleParagraph(DoxygenEntity& tag, std::string& translatedComment, std::string &arg) {
+  translatedComment += translateSubtree(tag) + arg;
 }
 void PyDocConverter::handlePlainString(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
   translatedComment += tag.data;
@@ -207,6 +244,17 @@ void PyDocConverter::handleTagPar(DoxygenEntity& tag, std::string& translatedCom
   tag.entityList.pop_front();
   handleParagraph(tag, translatedComment, dummy);
 }
+void PyDocConverter::handleTagImage(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
+  std::string dummy = " ";
+  if (tag.entityList.size() < 2)
+    return;
+  tag.entityList.pop_front();
+  translatedComment += "Image: ";
+  translatedComment += tag.entityList.begin()->data;
+  tag.entityList.pop_front();
+  if (tag.entityList.size())
+    translatedComment += "(" + tag.entityList.begin()->data + ")";
+}
 void PyDocConverter::handleTagParam(DoxygenEntity& tag, std::string& translatedComment, std::string&) {
   std::string dummy;
   if (tag.entityList.size() < 2) {
@@ -231,7 +279,7 @@ void PyDocConverter::handleTagWrap(DoxygenEntity& tag, std::string& translatedCo
     std::string tagData = translateSubtree(tag);
     // wrap the thing, ignoring whitespaces
     size_t wsPos = tagData.find_last_not_of("\n\t ");
-    if (wsPos != std::string::npos)
+    if (wsPos != std::string::npos && wsPos != tagData.size() - 1)
       translatedComment += arg + tagData.substr(0, wsPos + 1) + arg + tagData.substr(wsPos + 1);
     else
       translatedComment += arg + tagData + arg + " ";

Source/DoxygenTranslator/src/PyDocConverter.h

@@ -90,6 +90,10 @@ protected:
    * Insert 'Title: ...'
    */
   void handleTagPar(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
+  /*
+   * Insert 'Image: ...'
+   */
+  void handleTagImage(DoxygenEntity &tag, std::string &translatedComment, std::string &arg);
   /*
    * Format nice param description with type information
    */