[Opalvoip-svn] SF.net SVN: opalvoip: [20139] ptlib/branches/v2_2/include/ptlib/notifier.h

[<rjo...@us...>]

Revision: 20139
          http://opalvoip.svn.sourceforge.net/opalvoip/?rev=20139&view=rev
Author:   rjongbloed
Date:     2008-04-28 16:16:46 -0700 (Mon, 28 Apr 2008)

Log Message:
-----------
Updated documentation, thanks Stefano Sabatini

Modified Paths:
--------------
    ptlib/branches/v2_2/include/ptlib/notifier.h

Modified: ptlib/branches/v2_2/include/ptlib/notifier.h
===================================================================
--- ptlib/branches/v2_2/include/ptlib/notifier.h	2008-04-28 14:17:59 UTC (rev 20138)
+++ ptlib/branches/v2_2/include/ptlib/notifier.h	2008-04-28 23:16:46 UTC (rev 20139)
@@ -7,29 +7,27 @@
 ///////////////////////////////////////////////////////////////////////////////
 // General notification mechanism from one object to another
 
-/** This class is the #PSmartObject# contents of the #PNotifier#
-   class.
-
+/**
    This is an abstract class for which a descendent is declared for every
-   function that may be called. The #PDECLARE_NOTIFIER# macro makes this
+   function that may be called. The #PDECLARE_NOTIFIER macro makes this
    declaration.
 
-   The #PNotifier# and PNotifierFunction classes build a completely type
+   The #PNotifier and #PNotifierFunction classes build a completely type
    safe mechanism for calling arbitrary member functions on classes. The
    "pointer to a member function" capability built into C++ makes the
    assumption that the function name exists in an ancestor class. If you wish
-   to call a member function name that does {\bf not} exist in any ancestor
+   to call a member function name that does <b>not</b> exist in any ancestor
    class, very type unsafe casting of the member functions must be made. Some
    compilers will even refuse to do it at all!
 
    To overcome this problem, as this mechanism is highly desirable for callback
-   functions in the GUI part of the PWLib library, these classes and a macro
+   functions in the GUI part of the PTLib library, these classes and a macro
    are used to create all the classes and declarations to use polymorphism as
    the link between the caller, which has no knowledege of the function, and
    the receiver object and member function.
 
    This is most often used as the notification of actions being take by
-   interactors in the PWLib library.
+   interactors in the PTLib library.
  */
 class PNotifierFunction : public PSmartObject
 {
@@ -38,7 +36,7 @@
   public:
     /// Create a notification function instance.
     PNotifierFunction(
-      void * obj    ///< Object instance that the function will be called on.
+      void * obj    ///< Object instance on which the function will be called on.
     ) { object = PAssertNULL(obj); }
 
     /** Execute the call to the actual notification function on the object
@@ -56,10 +54,8 @@
 };
 
 
-/** This class is the #PSmartPointer# to the #PNotifierFunction#
-   class.
-
-   The PNotifier and #PNotifierFunction# classes build a completely type
+/**
+   The #PNotifier and #PNotifierFunction classes build a completely type
    safe mechanism for calling arbitrary member functions on classes. The
    "pointer to a member function" capability built into C++ makes the
    assumption that the function name exists in an ancestor class. If you wish
@@ -68,13 +64,13 @@
    compilers will even refuse to do it at all!
 
    To overcome this problem, as this mechanism is highly desirable for callback
-   functions in the GUI part of the PWLib library, these classes and a macro
+   functions in the GUI part of the PTLib library, these classes and a macro
    are used to create all the classes and declarations to use polymorphism as
    the link between the caller, which has no knowledege of the function, and
    the receiver object and member function.
 
    This is most often used as the notification of actions being take by
-   interactors in the PWLib library.
+   interactors in the PTLib library.
  */
 class PNotifier : public PSmartPointer
 {
@@ -102,25 +98,25 @@
 
 
 /** Declare a notifier object class.
-  This macro declares the descendent class of #PNotifierFunction# that
-  will be used in instances of #PNotifier# created by the
-  #PCREATE_NOTIFIER# or #PCREATE_NOTIFIER2# macros.
+  This macro declares the descendent class of #PNotifierFunction that
+  will be used in instances of #PNotifier created by the
+  #PCREATE_NOTIFIER or #PCREATE_NOTIFIER2 macros.
 
   The macro is expected to be used inside a class declaration. The class it
   declares will therefore be a nested class within the class being declared.
   The name of the new nested class is derived from the member function name
   which should guarentee the class names are unique.
 
-  The #notifier# parameter is the class of the function that will be
-  calling the notification function. The #notifiee# parameter is the
+  The \p notifier parameter is the class of the function that will be
+  calling the notification function. The \p notifiee parameter is the
   class to which the called member function belongs. Finally the
-  #func# parameter is the name of the member function to be
+  \p func parameter is the name of the member function to be
   declared.
 
   This macro will also declare the member function itself. This will be:
-\begin{verbatim}
+\verbatim
       void func(notifier & n, INT extra)
-\end{verbatim}
+\endverbatim
 
   The implementation of the function is left for the user.
  */
@@ -135,24 +131,25 @@
   virtual void func(notifier & note, INT extra)
 
 /** Create a notifier object instance.
-  This macro creates an instance of the particular #PNotifier# class using
-  the #func# parameter as the member function to call.
+  This macro creates an instance of the particular #PNotifier class using
+  the \p func parameter as the member function to call.
 
-  The #obj# parameter is the instance to call the function against.
-  If the instance to be called is the current instance, ie #obj# is
-  to #this# the the #PCREATE_NOTIFIER# macro should be used.
+  The \p obj parameter is the instance to call the function against.
+  If the instance to be called is the current instance, ie if \p obj is
+  \p this then the #PCREATE_NOTIFIER macro should be used.
  */
 #define PCREATE_NOTIFIER2(obj, func) PNotifier(new func##_PNotifier(obj))
 
 /** Create a notifier object instance.
-  This macro creates an instance of the particular #PNotifier# class using
-  the #func# parameter as the member function to call.
+  This macro creates an instance of the particular #PNotifier class using
+  the \p func parameter as the member function to call.
 
-  The #this# object is used as the instance to call the function
-  against. The #PCREATE_NOTIFIER2# macro may be used if the instance to be
+  The \p this object is used as the instance to call the function
+  against. The #PCREATE_NOTIFIER2 macro may be used if the instance to be
   called is not the current object instance.
  */
 #define PCREATE_NOTIFIER(func) PCREATE_NOTIFIER2(this, func)
 
 #endif
 
+


This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.