Added some docs, updated project-plan

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

Doc/Devel/plan-gsoc-2012.txt

@@ -79,6 +79,8 @@ Functionality
 
     Doxygen tags:
     
+    All tags: -OK-     
+
     \a - translated to <i></i> in JD, surrounded with _ in PD
     \addindex - ignored
     \addtogroup - ignored
@@ -257,12 +259,12 @@ Optional functionality
 That section describes some complex cases where the current code
 does not behave really well. Like a short to-do list of special cases.
 
-- When translating functions with default parameters in swig to
+-OK- When translating functions with default parameters in swig to
 java, it creates overloaded functions with all the parameters
 except the default ones. We need to copy the doxygen comment to
 such functions and correct the list of @param tags.
 
-- In doxygen there is a special tags (and even a special option)
+-OK- In doxygen there is a special tags (and even a special option)
 to create links to some code members from the current comment.
 Sometimes it needs a type of parameters specified because of the
 overloaded functions. And the same linking tags are supported in JD,
@@ -304,6 +306,15 @@ The following test cases will be implemented:
 -OK- Class comment, with all doxygen tags, including
   ignored ones.
   
+The list of all tests, in form of shell commands to make it simple
+to test project by copying the text below into terminal program.
+make doxygen_parsing.cpptest -s
+make doxygen_translate.cpptest -s
+make doxygen_translate_all_tags.cpptest -s
+make doxygen_basic_translate.cpptest -s
+make doxygen_basic_notranslate.cpptest -s
+make doxygen_translate_links.cpptest -s
+
   
 Refactoring
 ===========
@@ -313,7 +324,7 @@ All the code in directory _DoxygenTranslator_ should be refactored:
 -OK- most static methods should be normal members
 -OK- replace C arrays of strings and sequential searches with STL data
   structures and algorithms.
-- use singletons instead of class instantiaion for each comment found.
+-OK- use singletons instead of class instantiaion for each comment found.
 
 
 Documentation
@@ -324,4 +335,5 @@ SWIG documentation will contain:
 -OK- list of implemented features (types and placements of comments)
 -OK- list of unimplemented features (types and placements of comments)
 -OK- list of tags and their translations (all Doxygen tags).
+-OK- some amount of debugging and development information
 

Doc/Manual/Contents.html

@@ -1719,7 +1719,8 @@
 <li><a href="Doxygen.html#Doxygen_developer_details">Developer Information</a>
 <ul>
 <li><a href="Doxygen.html#Doxygen_module_design">Module Design</a>
-<li><a href="Doxygen.html#Doxygen_debugging_commands">Debugging commands</a>
+<li><a href="Doxygen.html#Doxygen_debugging_commands">Debugging Doxygen parser and translator</a>
+<li><a href="Doxygen.html#Doxygen_debugging_commands">Tests</a>
 </ul>
 <li><a href="Doxygen.html#Doxygen_language_extension">Extending to Other Languages</a>
 </ul>

Doc/Manual/Doxygen.html

@@ -32,7 +32,8 @@
 <li><a href="#Doxygen_developer_details">Developer Information</a>
 <ul>
 <li><a href="#Doxygen_module_design">Module Design</a>
-<li><a href="#Doxygen_debugging_commands">Debugging commands</a>
+<li><a href="#Doxygen_debugging_commands">Debugging Doxygen parser and translator</a>
+<li><a href="#Doxygen_debugging_commands">Tests</a>
 </ul>
 <li><a href="#Doxygen_language_extension">Extending to Other Languages</a>
 </ul>
@@ -1282,7 +1283,7 @@ This module builds its own private parse tree and hands it to a separate class f
 For example, <tt>JavaDocConverter</tt> is the JavaDoc module class.
 </p>
 
-<H3><a name="Doxygen_debugging_commands"></a>39.5.2 Debugging commands</H3>
+<H3><a name="Doxygen_debugging_commands"></a>39.5.2 Debugging Doxygen parser and translator</H3>
 
 
 <p>
@@ -1294,6 +1295,43 @@ There are two handy command line switches, that enable lots of detailed debug in
   -debug-doxygen-translator - Display Doxygen translator module debugging information
 </pre></div>
 
+<H3><a name="Doxygen_tests"></a>39.5.3 Tests</H3>
+
+
+<p>
+This part of SWIG currently has 6 runtime tests in both Java and Python.
+</p>
+
+<div class="shell"><pre>
+  doxygen_parsing
+  doxygen_translate
+  doxygen_translate_all_tags
+  doxygen_basic_translate
+  doxygen_basic_notranslate
+  doxygen_translate_links
+</pre></div>
+
+<p>
+All this tests are included in common.mk and are build with the commands like 'make check-test-suite'
+or 'make check-python-test-suite'. To run them individually, type 'make <testname>.cpptest -s' in the
+language-specific subdir in Examples\test-suite.
+<br>
+Runtime tests in Java are implemented using JavaDoc doclets. To make that work, you
+should have tools.jar from the JDK in your classpath. Or you should have JAVA_HOME
+environmental var defined and pointing to the JDK location.
+<br>
+The Java's comment parsing code (the testing part) is located in commentParser.java.
+You may see it to understand how the checking process works. There is also a possibility
+to run that file as stand-alone program, with 'java commentParser <some java package>',
+and it will print the list of comments found in the specified dir (in the format it's used
+in runtime tests). So, when you want to create the new test of Doxygen comment translator,
+just copy any existing one, and replace the actual comment content (section of entries in
+form 'wantedComments.put(...)' with the output of the above command.
+<br>
+Runtime tests in Python are just plain strings comparison with the use of __doc__
+properties.
+</p>
+
 <H2><a name="Doxygen_language_extension"></a>39.6 Extending to Other Languages</H2>