integrate Doxygen into SCons build. some doc fixes

SConstruct

@@ -31,7 +31,7 @@ from Buildhelper import *
 OPTIONSCACHEFILE = 'optcache' 
 CUSTOPTIONSFILE  = 'custom-options'
 SRCDIR           = 'src'
-BINDIR           = 'src/bin'
+BINDIR           = 'bin'
 TESTDIR          = 'tests'
 VERSION          = '3+alpha.01'
 #-----------------------------------Configuration
@@ -137,6 +137,7 @@ Special Targets:
      build   : just compile and link
      testcode: additionally compile the Testsuite
      check   : build and run the Testsuite
+     doc     : generate documetation (Doxygen)
      install : install created artifacts at PREFIX
      src.tar : create source tarball
      doc.tar : create developer doc tarball
@@ -243,22 +244,41 @@ def defineBuildTargets(env, artifacts):
     SConscript(dirs=[TESTDIR], exports='env artifacts corelib')
 
 
-def defineInstallTargets(env, artifacts):
-    """ define install locations and cleanup after the build.
+
+def definePostBuildTargets(env, artifacts):
+    """ define further actions after the core build (e.g. Documentaion).
         define alias targets to trigger the installing.
     """
+    ib = env.Alias('install-bin', '$DESTDIR/bin')
+    il = env.Alias('install-lib', '$DESTDIR/lib')
+    env.Alias('install', [ib, il])
+    
+    build = env.Alias('build', '$BINDIR')
+    allbu = env.Alias('allbuild', build+artifacts['testsuite'])
+    env.Default('build')
+    # additional files to be cleaned when cleaning 'build'
+    env.Clean ('build', [ 'scache.conf', '.sconf_temp', '.sconsign.dblite', 'config.log'])
+
+    # Doxygen documentation
+    # Note: at the moment we only depend on Doxyfile
+    #       obviousely, we should depend on all sourcefiles
+    #       real Doxygen builder for scons is under developement for 0.97
+    #       so for the moment I prefere not to bother
+    doxyfile = File('doc/devel/Doxyfile')
+    env.NoClean(doxyfile)
+    doxydoc = artifacts['doxydoc'] = [ Dir('doc/devel/html'), Dir('doc/devel/latex') ]
+    env.Command(doxydoc, doxyfile, "doxygen Doxyfile 2>&1 |tee ,doxylog",  chdir='doc/devel')
+    env.Clean ('doc/devel', doxydoc + ['doc/devel/,doxylog'])
+
+
+def defineInstallTargets(env, artifacts):
+    """ define some artifacts to be installed into target locations.
+    """
     env.Install(dir = '$DESTDIR/bin', source=artifacts['cinelerra'])
     env.Install(dir = '$DESTDIR/lib', source=artifacts['plugins'])
     env.Install(dir = '$DESTDIR/bin', source=artifacts['tools'])
     
-    ib = env.Alias('install-bin', '$DESTDIR/bin')
-    il = env.Alias('install-lib', '$DESTDIR/lib')
-    env.Alias('install', [ib, il])
-    
-    env.Alias('build', '$BINDIR')
-    env.Default('build')
-    # additional files to be cleaned when cleaning 'build'
-    env.Clean ('build', [ 'scache.conf', '.sconf_temp', '.sconsign.dblite', 'config.log'])
+    env.Install(dir = '$DESTDIR/share/doc/cinelerra$VERSION/devel', source=artifacts['doxydoc'])
 
 #####################################################################
 
@@ -286,5 +306,6 @@ artifacts = {}
 
 definePackagingTargets(env, artifacts)
 defineBuildTargets(env, artifacts)
+definePostBuildTargets(env, artifacts)
 defineInstallTargets(env, artifacts)
 

admin/scons/Buildhelper.py

@@ -46,16 +46,17 @@ def isHelpRequest():
 
 
 
-def srcSubtree(env,tree,isShared=False, **args):
+def srcSubtree(env,tree,isShared=False,builder=None, **args):
     """ convienience wrapper: scans the given subtree, which is
         relative to the current SConscript, find all source files and
         declare them as Static or SharedObjects for compilation
     """
     root = env.subst(tree)  # expand Construction Vars
-    if isShared:
-        builder = lambda f: env.SharedObject(f, **args)
-    else:
-        builder = lambda f: env.Object(f, **args)
+    if not builder:
+        if isShared:
+            builder = lambda f: env.SharedObject(f, **args)
+        else:
+            builder = lambda f: env.Object(f, **args)
         
     return [builder(f) for f in scanSrcSubtree(root)] 
 

src/common/test/suite.cpp

@@ -95,7 +95,10 @@ namespace test
    *  either as a member of one of the specified groups, or direcly
    *  by its testID. Any test is automatically added to the groupID
    *  #ALLGROUP
+   *  @param test the Launcher object used to run this test
+   *  @param testID unique ID to refere to this test (will be used as std::map key)
    *  @param groups List of group-IDs selected by whitespace
+   * 
    */
   void 
   Suite::enroll (Launcher* test, string testID, string groups)

src/common/test/testoption.cpp

@@ -115,9 +115,6 @@ namespace test
   
   
 
-  /** @intern forward the accummulated help messages from 
-   *  all contained option defintions to the outputstream 
-   */
   ostream& 
   operator<< (ostream& os, const TestOption& to)
     {

src/common/test/testoption.hpp

@@ -65,7 +65,9 @@ namespace test
       friend ostream& operator<< (ostream&, const TestOption&);
     };
   
-  /** for outputting the help messages. */
+    
+  /** for outputting the help messages. Forward accummulated 
+   *  help messages from all contained option defintions */
   ostream& operator<< (ostream& os, const TestOption& to);
  
   

tests/components/common/factorytest.cpp

@@ -37,10 +37,11 @@ namespace cinelerra
       public:
       };
       
-    ///// @test the various object creation factories
-    ///// @see  cinelerra::Factory
-    ///// @todo still to be written...
-    /////
+    /**********************************************************
+     * @test the various object creation factories
+     * @see  cinelerra::Factory
+     * @todo still to be written...
+     */
     class Factory_test : public Test
       {
         virtual void run(Arg arg) 

tests/components/common/test/cmdlinewrappertest.cpp

@@ -43,7 +43,7 @@ namespace util
     {
     
   
-    ///// @test for util::Cmndline, wrapping various example cmdlines
+    /** @test for util::Cmdline, wrapping various example cmdlines */
     class CmdlineWrapper_test : public Test
       {
         virtual void run (Arg arg)
@@ -80,6 +80,9 @@ namespace util
               ENSURE (token == theCmdline[i++]);
           }
         
+        /** @test wrapping a (albeit faked) standard commandline 
+         *        given as (argc, argv[])
+         */
         void testStandardCmdlineformat()
           {
             char* fakeArg[3] = {"CMD", "one ", "two"};

tests/components/common/test/testoptiontest.cpp

@@ -33,11 +33,12 @@ using std::endl;
 namespace test
   {
   
-  ///// @test for test::TestOption, parsing of commandline options
-  /////       for running collections of Tests
-  ///// @see test::Suite
-  ///// @see util::Cmdline
-  /////
+  /****************************************************************
+   * invokes the TestOption parser for various example commandlines
+   * @test for test::TestOption, parsing of commandline options
+   * @see test::Suite
+   * @see util::Cmdline
+   */
   class TestOption_test : public Test
     {
       virtual void run(Arg arg)
@@ -52,6 +53,7 @@ namespace test
           additionalCmd2();
         }
       
+      /** @test performs the actual test for the option parser test::TestOption */
       void doIt (const string cmdline)
         {
           std::cout << "Testing invocation with cmdline: " << cmdline << "..." << endl;

tests/components/helloworldtest.cpp

@@ -30,7 +30,10 @@ namespace cinelerra
   namespace test
     {
 
-    ///// @test demo of using the test framework
+    /******************************************
+     * Helooooooo to the world of TDD
+     * @test demo of using the test framework
+     */
     class HelloWorld_test : public Test
       {
         virtual void run(Arg arg)