mac paths updated
[wxWidgets.git] / interface / memory.h
index d2b306d6b45902c78d65de48724f702a2c0e9839..ec1fbed3de67436f7c0c8c78ae50ea45a625afc7 100644 (file)
@@ -1,6 +1,6 @@
 /////////////////////////////////////////////////////////////////////////////
 // Name:        memory.h
-// Purpose:     documentation for wxDebugStreamBuf class
+// Purpose:     interface of wxDebugStreamBuf
 // Author:      wxWidgets team
 // RCS-ID:      $Id$
 // Licence:     wxWindows license
@@ -9,55 +9,54 @@
 /**
     @class wxDebugStreamBuf
     @wxheader{memory.h}
-    
+
     This class allows you to treat debugging output in a similar
     (stream-based) fashion on different platforms. Under
     Windows, an ostream constructed with this buffer outputs
     to the debugger, or other program that intercepts debugging
     output. On other platforms, the output goes to standard error (cerr).
-    
+
     This is soon to be obsolete, replaced by wxLog functionality.
-    
+
     @library{wxbase}
     @category{FIXME}
-    
-    @seealso
-    Overview
+
+    @see Overview()
 */
-class wxDebugStreamBuf 
+class wxDebugStreamBuf
 {
 public:
-    
+
 };
 
 
+
 /**
     @class wxDebugContext
     @wxheader{memory.h}
-    
+
     A class for performing various debugging and memory tracing
     operations. Full functionality (such as printing out objects
     currently allocated) is only present in a debugging build of wxWidgets,
     i.e. if the __WXDEBUG__ symbol is defined. wxDebugContext
     and related functions and macros can be compiled out by setting
     wxUSE_DEBUG_CONTEXT to 0 is setup.h
-    
+
     @library{wxbase}
     @category{debugging}
-    
-    @seealso
-    Overview
+
+    @see Overview()
 */
-class wxDebugContext 
+class wxDebugContext
 {
 public:
     /**
         Checks the memory blocks for errors, starting from the currently set
         checkpoint.
-        
-        @returns Returns the number of errors, so a value of zero represents
-                   success. Returns -1 if an error was detected that
-                   prevents further checking.
+
+        @return Returns the number of errors, so a value of zero represents
+                 success. Returns -1 if an error was detected that
+                 prevents further checking.
     */
     int Check();
 
@@ -65,8 +64,8 @@ public:
         Performs a memory dump from the currently set checkpoint, writing to the
         current debug stream. Calls the @b Dump member function for each wxObject
         derived instance.
-        
-        @returns @true if the function succeeded, @false otherwise.
+
+        @return @true if the function succeeded, @false otherwise.
     */
     bool Dump();
 
@@ -74,8 +73,8 @@ public:
         Returns @true if the memory allocator checks all previous memory blocks for
         errors.
         By default, this is @false since it slows down execution considerably.
-        
-        @sa SetCheckPrevious()
+
+        @see SetCheckPrevious()
     */
     bool GetCheckPrevious();
 
@@ -84,8 +83,8 @@ public:
         delete
         operators store or use information about memory allocation. Otherwise,
         a straight malloc and free will be performed by these operators.
-        
-        @sa SetDebugMode()
+
+        @see SetDebugMode()
     */
     bool GetDebugMode();
 
@@ -96,19 +95,17 @@ public:
         a different level will only have an effect if trace statements in the
         application
         specify a value other than one.
-        
         This is obsolete, replaced by wxLog functionality.
-        
-        @sa SetLevel()
+
+        @see SetLevel()
     */
     int GetLevel();
 
     /**
         Returns the output stream associated with the debug context.
-        
         This is obsolete, replaced by wxLog functionality.
-        
-        @sa SetStream()
+
+        @see SetStream()
     */
     ostream GetStream();
 
@@ -116,7 +113,6 @@ public:
         Returns a pointer to the output stream buffer associated with the debug context.
         There may not necessarily be a stream buffer if the stream has been set
         by the user.
-        
         This is obsolete, replaced by wxLog functionality.
     */
     streambuf* GetStreamBuf();
@@ -124,18 +120,17 @@ public:
     /**
         Returns @true if there is a stream currently associated
         with the debug context.
-        
         This is obsolete, replaced by wxLog functionality.
-        
-        @sa SetStream(), GetStream()
+
+        @see SetStream(), GetStream()
     */
     bool HasStream();
 
     /**
         Prints a list of the classes declared in this application, giving derivation
         and whether instances of this class can be dynamically created.
-        
-        @sa PrintStatistics()
+
+        @see PrintStatistics()
     */
     bool PrintClasses();
 
@@ -143,21 +138,21 @@ public:
         Performs a statistics analysis from the currently set checkpoint, writing
         to the current debug stream. The number of object and non-object
         allocations is printed, together with the total size.
-        
-        @param detailed 
-        If @true, the function will also print how many
-        objects of each class have been allocated, and the space taken by
-        these class instances.
-        
-        @sa PrintStatistics()
+
+        @param detailed
+            If @true, the function will also print how many
+            objects of each class have been allocated, and the space taken by
+            these class instances.
+
+        @see PrintStatistics()
     */
-    bool PrintStatistics(bool detailed = @true);
+    bool PrintStatistics(bool detailed = true);
 
     /**
         Tells the memory allocator to check all previous memory blocks for errors.
         By default, this is @false since it slows down execution considerably.
-        
-        @sa GetCheckPrevious()
+
+        @see GetCheckPrevious()
     */
     void SetCheckPrevious(bool check);
 
@@ -165,25 +160,24 @@ public:
         Sets the current checkpoint: Dump and PrintStatistics operations will
         be performed from this point on. This allows you to ignore allocations
         that have been performed up to this point.
-        
-        @param all 
-        If @true, the checkpoint is reset to include all
-        memory allocations since the program started.
+
+        @param all
+            If @true, the checkpoint is reset to include all
+            memory allocations since the program started.
     */
-    void SetCheckpoint(bool all = @false);
+    void SetCheckpoint(bool all = false);
 
     /**
         Sets the debug mode on or off. If debug mode is on, the wxObject new and delete
         operators store or use information about memory allocation. Otherwise,
         a straight malloc and free will be performed by these operators.
-        
         By default, debug mode is on if __WXDEBUG__ is defined. If the application
         uses this function, it should make sure that all object memory allocated
         is deallocated with the same value of debug mode. Otherwise, the
         delete operator might try to look for memory information that does not
         exist.
-        
-        @sa GetDebugMode()
+
+        @see GetDebugMode()
     */
     void SetDebugMode(bool debug);
 
@@ -201,10 +195,9 @@ public:
         a different level will only have an effect if trace statements in the
         application
         specify a value other than one.
-        
         This is obsolete, replaced by wxLog functionality.
-        
-        @sa GetLevel()
+
+        @see GetLevel()
     */
     void SetLevel(int level);
 
@@ -213,7 +206,6 @@ public:
         called after
         all files with global instances of wxDebugContextDumpDelayCounter have run
         their destructors.
-        
         The shutdown function must be take no parameters and return nothing.
     */
     void SetShutdownNotifyFunction(wxShutdownNotifyFunction func);
@@ -222,7 +214,6 @@ public:
         Sets the debugging stream to be the debugger (Windows) or standard error (other
         platforms).
         This is the default setting. The existing stream will be flushed and deleted.
-        
         This is obsolete, replaced by wxLog functionality.
     */
     bool SetStandardError();
@@ -231,51 +222,74 @@ public:
         Sets the stream and optionally, stream buffer associated with the debug context.
         This operation flushes and deletes the existing stream (and stream buffer if
         any).
-        
         This is obsolete, replaced by wxLog functionality.
-        
-        @param stream 
-        Stream to associate with the debug context. Do not set this to @NULL.
-        
-        @param streamBuf 
-        Stream buffer to associate with the debug context.
+
+        @param stream
+            Stream to associate with the debug context. Do not set this to @NULL.
+        @param streamBuf
+            Stream buffer to associate with the debug context.
     */
-    void SetStream(ostream* stream, streambuf* streamBuf = @NULL);
+    void SetStream(ostream* stream, streambuf* streamBuf = NULL);
 };
 
 
+
 // ============================================================================
 // Global functions/macros
 // ============================================================================
 
+/** @ingroup group_funcmacro_log */
+//@{
+
 /**
-    @b NB: This function is now obsolete, replaced by @ref overview_logfunctions
-    "Log functions".
-    
-    Calls wxTraceLevel with printf-style variable argument syntax. Output
-    is directed to the current output stream (see wxDebugContext).
-    The first argument should be the level at which this information is appropriate.
-    It will only be output if the level returned by wxDebugContext::GetLevel is
-    equal to or greater than
-    this value.
+    @deprecated Use one of the wxLogTrace() functions or one of the
+                wxVLogTrace() functions instead.
+
+    Calls wxTrace() with printf-style variable argument syntax. Output is
+    directed to the current output stream (see wxDebugContext).
+
+    @header{wx/memory.h}
 */
-#define WXTRACELEVEL()     /* implementation is private */
+#define WXTRACE(format, ...)
 
 /**
-    @b NB: This function is now obsolete, replaced by @ref overview_logfunctions
-    "Log functions".
-    
-    Takes printf-style variable argument syntax. Output
-    is directed to the current output stream (see wxDebugContext).
+    @deprecated Use one of the wxLogTrace() functions or one of the
+                wxVLogTrace() functions instead.
+
+    Calls wxTraceLevel with printf-style variable argument syntax. Output is
+    directed to the current output stream (see wxDebugContext). The first
+    argument should be the level at which this information is appropriate. It
+    will only be output if the level returned by wxDebugContext::GetLevel is
+    equal to or greater than this value.
+
+    @header{wx/memory.h}
 */
-void wxTrace(const wxString& fmt, ... );
+#define WXTRACELEVEL(level, format, ...)
 
 /**
-    @b NB: This macro is now obsolete, replaced by @ref overview_logfunctions "Log
-    functions".
-    
-    Calls wxTrace with printf-style variable argument syntax. Output
-    is directed to the current output stream (see wxDebugContext).
+    @deprecated Use one of the wxLogTrace() functions or one of the
+                wxVLogTrace() functions instead.
+
+    Takes printf-style variable argument syntax. Output is directed to the
+    current output stream (see wxDebugContext).
+
+    @header{wx/memory.h}
 */
-#define Include files WXTRACE()     /* implementation is private */
+void wxTrace(const wxString& format, ...);
+
+/**
+    @deprecated Use one of the wxLogTrace() functions or one of the
+                wxVLogTrace() functions instead.
+
+    Takes @e printf() style variable argument syntax. Output is directed to the
+    current output stream (see wxDebugContext). The first argument should be
+    the level at which this information is appropriate. It will only be output
+    if the level returned by wxDebugContext::GetLevel() is equal to or greater
+    than this value.
+
+    @header{wx/memory.h}
+*/
+void wxTraceLevel(int level, const wxString& format, ...);
+
+//@}