--- a/doc/tutorial/tracing.texi	Thu Oct 08 13:59:26 2009 -0700
+++ b/doc/tutorial/tracing.texi	Thu Oct 08 17:57:06 2009 -0700
@@ -683,8 +683,26 @@
 
 @subsection What String do I use to Connect?
 
-The key to this question is found in the @code{ns-3} Doxygen as well.  It will
-be simplest just to walk through the ``CourseChanged'' example.
+The easiest way to do this is to grep around in the @ns-3 codebase for someone
+who has already figured it out,  You should always try to copy someone else's
+working code before you start to write your own.  Try something like:
+
+@verbatim
+  find . -name '*.cc' | xargs grep CourseChange | grep Connect
+@end verbatim
+
+and you may find your answer along with working code.  For example, in this
+case, @code{./ns-3-dev/examples/wireless/mixed-wireless.cc} has something
+just waiting for you to use:
+
+@verbatim
+  Config::Connect (``/NodeList/*/$ns3::MobilityModel/CourseChange'', 
+    MakeCallback (&CourseChangeCallback));
+@end verbatim
+
+If you cannot find any examples in the distribution, you can find this out
+from the @code{ns-3} Doxygen.  It will probably be simplest just to walk 
+through the ``CourseChanged'' example.
 
 Let's assume that you have just found the ``CourseChanged'' trace source in 
 ``The list of all trace sources'' and you want to figure out how to connect to
@@ -773,10 +791,39 @@
 
 @subsection What Return Value and Formal Arguments?
 
-This is a bit more involved.  There are two ways you can figure this out.
+The easiest way to do this is to grep around in the @ns-3 codebase for someone
+who has already figured it out,  You should always try to copy someone else's
+working code.  Try something like:
+
+@verbatim
+  find . -name '*.cc' | xargs grep CourseChange | grep Connect
+@end verbatim
+
+and you may find your answer along with working code.  For example, in this
+case, @code{./ns-3-dev/examples/wireless/mixed-wireless.cc} has something
+just waiting for you to use.  You will find
+
+@verbatim
+  Config::Connect (``/NodeList/*/$ns3::MobilityModel/CourseChange'', 
+    MakeCallback (&CourseChangeCallback));
+@end verbatim
+
+as a result of your grep.  The @code{MakeCallback} should indicate to you that
+there is a callback function there which you can use.  Sure enough, there is:
+
+@verbatim
+  static void
+  CourseChangeCallback (std::string path, Ptr<const MobilityModel> model)
+  {
+    ...
+  }
+@end verbatim
+
+If there are no examples to work from, this can be a bit more challenging.
 
 
 
 
 
 
+

--- a/wscript	Thu Oct 08 13:59:26 2009 -0700
+++ b/wscript	Thu Oct 08 17:57:06 2009 -0700
@@ -137,16 +137,6 @@
                    action="store_true", default=False,
                    dest='lcov_report')
 
-    opt.add_option('--doxygen',
-                   help=('Run doxygen to generate html documentation from source comments'),
-                   action="store_true", default=False,
-                   dest='doxygen')
-    opt.add_option('--doxygen-no-build',
-                   help=('Run doxygen to generate html documentation from source comments, '
-                         'but do not wait for ns-3 to finish the full build.'),
-                   action="store_true", default=False,
-                   dest='doxygen_no_build')
-
     opt.add_option('--run',
                    help=('Run a locally built program; argument can be a program name,'
                          ' or a command starting with the program name.'),
@@ -590,25 +580,12 @@
             raise Utils.WafError("Cannot run regression tests: building the ns-3 examples is not enabled"
                                  " (regression tests are based on examples)")
 
-#    if Options.options.check:
-#        Options.options.compile_targets += ',run-tests'
-#        if env['ENABLE_PYTHON_BINDINGS']:
-#            Options.options.compile_targets += ',ns3module,pybindgen-command'
-#        _run_check(bld)
-
-    if Options.options.doxygen_no_build:
-        doxygen()
-        raise SystemExit(0)
-
 def shutdown(ctx):
     bld = wutils.bld
     if wutils.bld is None:
         return
     env = bld.env
 
-    #if Options.commands['check']:
-    #    _run_waf_check()
-
     if Options.options.lcov_report:
         lcov_report()
 
@@ -626,25 +603,14 @@
     if Options.options.check:
         raise Utils.WafError("Please run `./test.py' now, instead of `./waf --check'")
 
-    if Options.options.doxygen:
-        doxygen()
-        raise SystemExit(0)
-
     check_shell(bld)
 
-    if Options.options.doxygen:
-        doxygen()
-        raise SystemExit(0)
-
-
 check_context = Build.BuildContext
 
 def check(bld):
     """run the equivalent of the old ns-3 unit tests using test.py"""
-    bld = wutils.bld
-    env = bld.env
-    wutils.run_python_program("test.py -c core", env)
-
+    env = wutils.bld.env
+    wutils.run_python_program("test.py -n -c core", env)
 
 class print_introspected_doxygen_task(Task.TaskBase):
     after = 'cc cxx cc_link cxx_link'
@@ -696,111 +662,6 @@
         wutils.run_argv([self.bld.env['PYTHON'], os.path.join("..", "utils", "python-unit-tests.py")],
                         self.bld.env, proc_env, force_no_valgrind=True)
 
-#class run_a_unit_test_task(Task.TaskBase):
-#    after = 'cc cxx cc_link cxx_link'
-#    color = 'BLUE'
-#
-#    def __init__(self, bld, name_of_test):
-#        self.bld = bld
-#        super(run_a_unit_test_task, self).__init__(generator=self)
-#        self.name_of_test = name_of_test
-#        try:
-#            program_obj = wutils.find_program("run-tests", self.bld.env)
-#        except ValueError, ex:
-#            raise Utils.WafError(str(ex))
-#        program_node = program_obj.path.find_or_declare(ccroot.get_target_name(program_obj))
-#        self.program_path = program_node.abspath(self.bld.env)
-#
-#    def __str__(self):
-#        return 'run-unit-test(%s)\n' % self.name_of_test
-#
-#    def runnable_status(self):
-#        return Task.RUN_ME
-#
-#    def run(self):
-#        #print repr([self.program_path, self.name_of_test])
-#        try:
-#            self.retval = wutils.run_argv([self.program_path, self.name_of_test], self.bld.env)
-#        except Utils.WafError:
-#            self.retval = 1
-#        #print "running test %s: exit with %i" % (self.name_of_test, retval)
-#        return 0
-#
-#class get_list_of_unit_tests_task(Task.TaskBase):
-#    after = 'cc cxx cc_link cxx_link'
-#    color = 'BLUE'
-#
-#    def __init__(self, bld):
-#        self.bld = bld
-#        super(get_list_of_unit_tests_task, self).__init__(generator=self)
-#        self.tests = []
-#
-#    def __str__(self):
-#        return 'get-unit-tests-list\n'
-#
-#    def runnable_status(self):
-#        return Task.RUN_ME
-#
-#    def run(self):
-#        try:
-#            program_obj = wutils.find_program("run-tests", self.bld.env)
-#        except ValueError, ex:
-#            raise Utils.WafError(str(ex))
-#        program_node = program_obj.path.find_or_declare(ccroot.get_target_name(program_obj))
-#        program_path = program_node.abspath(self.bld.env)
-#        proc = subprocess.Popen([program_path, "--ListTests"], stdout=subprocess.PIPE,
-#                                env=wutils.get_proc_env())
-#        self.tests = [l.rstrip() for l in proc.stdout.readlines()]
-#        retval = proc.wait()
-#        if retval:
-#            return retval
-#        test_tasks = []
-#        for name_of_test in self.tests:
-#            test_tasks.append(run_a_unit_test_task(self.bld, name_of_test))
-#        collector = collect_unit_test_results_task(self.bld, list(test_tasks))
-#        collector.run_after = list(test_tasks)
-#        self.more_tasks = [collector] + test_tasks
-#        
-#
-#class collect_unit_test_results_task(Task.TaskBase):
-#    after = 'run_a_unit_test_task'
-#    color = 'BLUE'
-#
-#    def __init__(self, bld, test_tasks):
-#        self.bld = bld
-#        super(collect_unit_test_results_task, self).__init__(generator=self)
-#        self.test_tasks = test_tasks
-#
-#    def __str__(self):
-#        return 'collect-unit-tests-results\n'
-#
-#    def runnable_status(self):
-#        for t in self.run_after:
-#            if not t.hasrun:
-#                return Task.ASK_LATER
-#        return Task.RUN_ME
-#
-#    def run(self):
-#        failed_tasks = []
-#        for task in self.test_tasks:
-#            if task.retval:
-#                failed_tasks.append(task)
-#        if failed_tasks:
-#            print "C++ UNIT TESTS: %i tests passed, %i failed (%s)." % \
-#                (len(self.test_tasks) - len(failed_tasks), len(failed_tasks),
-#                 ', '.join(t.name_of_test for t in failed_tasks))
-#            return 1
-#        else:
-#            print "C++ UNIT TESTS: all %i tests passed." % (len(self.test_tasks),)
-#            return 0
-#
-#
-#def _run_check(bld):
-#    task = get_list_of_unit_tests_task(bld)
-#    print_introspected_doxygen_task(bld)
-#    if bld.env['ENABLE_PYTHON_BINDINGS']:
-#        run_python_unit_tests_task(bld)
-
 def check_shell(bld):
     if 'NS3_MODULE_PATH' not in os.environ:
         return
@@ -835,11 +696,26 @@
     env = wutils.bld.env
     wutils.run_argv([shell], env, {'NS3_MODULE_PATH': os.pathsep.join(env['NS3_MODULE_PATH'])})
 
-def doxygen():
-    if not os.path.exists('doc/introspected-doxygen.h'):
-        Logs.warn("doc/introspected-doxygen.h does not exist; run waf check to generate it.")
+def doxygen(bld):
+    """do a full build, generate the introspected doxygen and then the doxygen"""
+    Scripting.build(bld)
+    env = wutils.bld.env
+    proc_env = wutils.get_proc_env()
 
-    ## run doxygen
+    try:
+        program_obj = wutils.find_program('print-introspected-doxygen', env)
+    except ValueError: 
+        Logs.warn("print-introspected-doxygen does not exist")
+        raise SystemExit(1)
+        return
+
+    prog = program_obj.path.find_or_declare(ccroot.get_target_name(program_obj)).abspath(env)
+    out = open(os.path.join('doc', 'introspected-doxygen.h'), 'w')
+
+    if subprocess.Popen([prog], stdout=out, env=proc_env).wait():
+        raise SystemExit(1)
+    out.close()
+
     doxygen_config = os.path.join('doc', 'doxygen.conf')
     if subprocess.Popen(['doxygen', doxygen_config]).wait():
         raise SystemExit(1)
@@ -876,9 +752,6 @@
     finally:
         os.chdir("..")
 
-
-
-
 ##
 ## The default WAF DistDir implementation is rather slow, because it
 ## first copies everything and only later removes unwanted files and