warnings eliminated, examples fixed, only doxygen_misc_constructs is not working now

Doc/Manual/Doxygen.html

@@ -790,6 +790,75 @@ Here is the list of these tags:
 </table>
 </pre></div>
 
+<p/>
+
+If one of the following Doxygen tags appears as the first tag in a
+comment, the whole comment block is ignored:
+<!-- see parser.y, function isStructuralDoxygen() -->
+
+</p>
+<div class="diagram"><pre>
+<table border="0">
+<tr>
+<td>\addtogroup</td>
+<td>\callgraph</td>
+<td>\callergraph</td>
+<td>\category</td>
+</tr>
+<tr>
+<td>\class</td>
+<td>\def</td>
+<td>\defgroup</td>
+<td>\dir</td>
+</tr>
+<tr>
+<td>\enum</td>
+<td>\example</td>
+<td>\file</td>
+<td>\fn</td>
+</tr>
+<tr>
+<td>\headerfile</td>
+<td>\hideinitializer</td>
+<td>\interface</td>
+<td>\internal</td>
+</tr>
+<tr>
+<td>\mainpage</td>
+<td>\name</td>
+<td>\namespace</td>
+<td>\nosubgrouping</td>
+</tr>
+<tr>
+<td>\overload</td>
+<td>\package</td>
+<td>\page</td>
+<td>\property</td>
+</tr>
+<tr>
+<td>\protocol</td>
+<td>\relates</td>
+<td>\relatesalso</td>
+<td>\showinitializer</td>
+</tr>
+<tr>
+<td>\struct</td>
+<td>\name</td>
+<td>\namespace</td>
+<td>\nosubgrouping</td>
+</tr>
+<tr>
+<td>\typedef</td>
+<td>\union</td>
+<td>\var</td>
+<td>\weakgroup</td>
+</tr>
+
+</table>
+</pre></div>
+
+
+
 <H3><a name="Doxygen_further_details"></a>39.3.4 Further Details</H3>
 
 

Examples/test-suite/doxygen_translate_all_tags.i

@@ -70,6 +70,8 @@ int func02(int a)
 
  
 /**
+ * Comment for \b func03().
+ *
  * \dir /somePath/someFolder
  *
  * \dontinclude someFile.h
@@ -176,6 +178,8 @@ int func05(int a)
 
  
 /**
+ * Comment for \b func06().
+ *
  * \interface someInterface someHeader.h "Header name"
  *
  * \latexonly
@@ -218,6 +222,8 @@ int func06(int a)
 
  
 /**
+ * Comment for \b func07().
+ *
  * \name someHeader.h
  *
  * \namespace someNamespace
@@ -384,4 +390,16 @@ int func10(int a, float b)
 {
 }
 
+
+/**
+ * \interface someInterface someHeader.h "Header name"
+ *
+ * Because of structural Doxygen command at the start of comment block,
+ * the whoile comment block is ignored. See parser.y, f. isStructuralDoxygen()
+ * or documentation for the list of commands.
+ */
+int func11(int a, float b)
+{
+}
+
 %}

Examples/test-suite/java/commentParser.java

@@ -2,6 +2,8 @@
 import com.sun.javadoc.*;
 import java.util.HashMap;
 import java.util.Map.Entry;
+import java.util.Map;
+import java.util.Set;
 import java.util.Iterator;
 import java.io.BufferedWriter;
 import java.io.OutputStreamWriter;
@@ -88,8 +90,15 @@ public class commentParser {
             }
         }
 
-        if (parsedComments.size() < wantedComments.size()) {
+        if (parsedComments.size() != wantedComments.size()) {
-            System.out.println("Found " + (wantedComments.size()-parsedComments.size()) + " missed comment(s)!");
+            System.out.println("Mismatch in the number of comments!\n    Expected: " +
+                               wantedComments.size() + "\n    Parsed: " +
+                               parsedComments.size());
+            System.out.println("Expected keys: ");
+            printKeys(wantedComments);
+            System.out.println("Parsed keys: ");
+            printKeys(parsedComments);
+
             errorCount++;
         }
 		
@@ -97,6 +106,14 @@ public class commentParser {
     }
 
     
+    private static void printKeys(Map map) {
+        Set<String> keys = map.keySet();
+        for (String key : keys) {
+            System.out.println("    " + key);
+        }
+    }
+    
+    
     public static void printCommentListForJavaSource() {
         Iterator< Entry<String, String> > it = parsedComments.entrySet().iterator();
         while (it.hasNext())

Examples/test-suite/java/doxygen_translate_all_tags_runme.java

@@ -51,8 +51,11 @@ public class doxygen_translate_all_tags_runme {
     		" and detailed description of some thing \n");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func03(int)",
+                       " Comment for <b>func03().</b>\n" +
                        " <i>italicword </i>\n" +
-    		" <i>emphazedWord </i>\n");
+    		" <i>emphazedWord </i>\n" +
+                " @ example someFile.txt\n" +
+                " Some details on using the example");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func04(int)",
                        " @exception SuperError \n" +
@@ -80,6 +83,7 @@ public class doxygen_translate_all_tags_runme {
     		" describing invariant. \n");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func06(int)",
+                       " Comment for <b>func06().</b>\n" +
                        " This will only appear in LATeX \n" +
     		" <ul> \n" +
     		" <li>Some unordered list \n" +
@@ -90,6 +94,7 @@ public class doxygen_translate_all_tags_runme {
     		" This will only appear in man\n");
     
     wantedComments.put("doxygen_translate_all_tags.doxygen_translate_all_tags.func07(int)",
+                       " Comment for <b>func07().</b>\n" +
                        " Note: Here \n" +
     		" is the note! \n" +
     		" This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts.\n" +

Source/DoxygenTranslator/src/JavaDocConverter.cpp

@@ -126,7 +126,7 @@ void JavaDocConverter::fillStaticTables() {
   tagHandlers["else"] = make_pair(&JavaDocConverter::handleTagIf, "Else: ");
   tagHandlers["elseif"] = make_pair(&JavaDocConverter::handleTagIf, "Else if: ");
   tagHandlers["endcond"] = make_pair(&JavaDocConverter::handleTagMessage, "End of conditional comment.");
-  // space prevents Javadoc to treat '@ example' as command. File name of
+  // space in second arg prevents Javadoc to treat '@ example' as command. File name of
   // example is still informative to user.
   tagHandlers["example"] = make_pair(&JavaDocConverter::handleTagSame, " example");
   tagHandlers["if"] = make_pair(&JavaDocConverter::handleTagIf, "If: ");
@@ -340,7 +340,9 @@ void JavaDocConverter::translateEntity(DoxygenEntity &tag,
   if (it != tagHandlers.end()) {
     (this->*(it->second.first))(tag, translatedComment, it->second.second);
   } else {
-      addError(WARN_DOXYGEN_COMMAND_ERROR, "Unknown doxygen or HTML tag: " + tag.typeOfEntity);
+      // do NOT print warning, since there are many tags, which are not
+      // translatable - many warnings hide important ones
+      // addError(WARN_DOXYGEN_COMMAND_ERROR, "Unknown doxygen or HTML tag: " + tag.typeOfEntity);
   }
 }