Formatting

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@54296 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/log.h

@@ -373,6 +373,115 @@ public:
     See @ref overview_wxlogoverview "log overview" for the descriptions of wxWidgets
     logging facilities.
 
+     @section overview_wxLog_Trace_Masks Deriving your own log target
+     
+        There are two functions which must be implemented by any derived class to
+        actually process the log messages: DoLog() and
+        DoLogString(). The second function receives a string
+        which just has to be output in some way and the easiest way to write a new log
+        target is to override just this function in the derived class. If more control
+        over the output format is needed, then the first function must be overridden
+        which allows to construct custom messages depending on the log level or even
+        do completely different things depending on the message severity (for example,
+        throw away all messages except warnings and errors, show warnings on the
+        screen and forward the error messages to the user's (or programmer's) cell
+        phone - maybe depending on whether the timestamp tells us if it is day or
+        night in the current time zone).
+        There also functions to support message buffering. Why are they needed?
+        Some of wxLog implementations, most notably the standard wxLogGui class,
+        buffer the messages (for example, to avoid showing the user a zillion of modal
+        message boxes one after another -- which would be really annoying).
+        Flush() shows them all and clears the buffer contents.
+        This function doesn't do anything if the buffer is already empty.
+        See also:
+        @li Flush()
+        @li FlushActive()
+
+     @section overview_wxLog_Trace_Masks Using trace masks
+
+        The functions below allow some limited customization of wxLog behaviour
+        without writing a new log target class (which, aside of being a matter of
+        several minutes, allows you to do anything you want).
+        The verbose messages are the trace messages which are not disabled in the
+        release mode and are generated by wxLogVerbose(). They
+        are not normally shown to the user because they present little interest, but
+        may be activated, for example, in order to help the user find some program
+        problem.
+        As for the (real) trace messages, their handling depends on the settings of
+        the (application global) @e trace mask which can either be specified using
+        SetTraceMask(), GetTraceMask() and wxLogTrace() which takes an integer mask
+        or using AddTraceMask() for string trace masks.
+        The difference between bit-wise and string trace masks is that a message using
+        integer trace mask will only be logged if all bits of the mask are set in the
+        current mask while a message using string mask will be logged simply if the
+        mask had been added before to the list of allowed ones.
+        For example,
+        
+        @begincode
+        wxLogTrace( wxTraceRefCount|wxTraceOleCalls, "Active object ref count: %d", nRef );
+        @endcode
+
+        will do something only if the current trace mask contains both
+        @c wxTraceRefCount and @c wxTraceOle, but
+
+        @begincode
+        wxLogTrace( wxTRACE_OleCalls, "IFoo::Bar() called" );
+        @endcode
+        
+        will log the message if it was preceded by
+        
+        @begincode
+        wxLog::AddTraceMask( wxTRACE_OleCalls);
+        @endcode
+
+        Using string masks is simpler and allows to easily add custom ones, so this is
+        the preferred way of working with trace messages. The integer trace mask is
+        kept for compatibility and for additional (but very rarely needed) flexibility
+        only.
+        The standard trace masks are given in wxLogTrace() documentation.
+        Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
+        to all the messages. The format of the time stamp may be changed: it can be
+        any string with % specifications fully described in the documentation of the
+        standard @e strftime() function. For example, the default format is
+        "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] "
+        (without quotes) for the current date. Setting an empty string as the time
+        format disables timestamping of the messages completely.
+        @note Timestamping is disabled for Visual C++ users in debug builds by
+        default because otherwise it would be impossible to directly go to the line
+        from which the log message was generated by simply clicking in the debugger
+        window on the corresponding error message. If you wish to enable it, please
+        use SetTimestamp() explicitly. See also
+        @li AddTraceMask()
+        @li RemoveTraceMask()
+        @li ClearTraceMasks()
+        @li GetTraceMasks()
+        @li IsAllowedTraceMask()
+        @li SetVerbose()
+        @li GetVerbose()
+        @li SetTimestamp()
+        @li GetTimestamp()
+        @li SetTraceMask()
+        @li GetTraceMask()
+        @li SetRepetitionCounting()
+        @li GetRepetitionCounting()
+
+     @section overview_wxLog_Target Manipulating the log target
+
+        The functions in this section work with and manipulate the active log
+        target. The OnLog() is called by the @e wxLogXXX() functions
+        and invokes the DoLog() of the active log target if any.
+        Get/Set methods are used to install/query the current active target and,
+        finally, DontCreateOnDemand() disables the automatic creation of a standard
+        log target if none actually exists. It is only useful when the application
+        is terminating and shouldn't be used in other situations because it may
+        easily lead to a loss of messages. See also
+        @li OnLog()
+        @li GetActiveTarget()
+        @li SetActiveTarget()
+        @li DontCreateOnDemand()
+        @li Suspend()
+        @li Resume()
+
     @library{wxcore}
     @category{logging}
 
@@ -397,75 +506,6 @@ public:
     */
     static void ClearTraceMasks();
 
-    /**
-        The functions below allow some limited customization of wxLog behaviour
-        without writing a new log target class (which, aside of being a matter of
-        several minutes, allows you to do anything you want).
-        The verbose messages are the trace messages which are not disabled in the
-        release mode and are generated by wxLogVerbose(). They
-        are not normally shown to the user because they present little interest, but
-        may be activated, for example, in order to help the user find some program
-        problem.
-        As for the (real) trace messages, their handling depends on the settings of
-        the (application global) @e trace mask. There are two ways to specify it:
-        either by using SetTraceMask() and
-        GetTraceMask() and using
-        wxLogTrace() which takes an integer mask or by using
-        AddTraceMask() for string trace masks.
-        The difference between bit-wise and string trace masks is that a message using
-        integer trace mask will only be logged if all bits of the mask are set in the
-        current mask while a message using string mask will be logged simply if the
-        mask had been added before to the list of allowed ones.
-        For example,
-
-        will do something only if the current trace mask contains both
-        @c wxTraceRefCount and @c wxTraceOle, but
-
-        will log the message if it was preceded by
-
-        Using string masks is simpler and allows to easily add custom ones, so this is
-        the preferred way of working with trace messages. The integer trace mask is
-        kept for compatibility and for additional (but very rarely needed) flexibility
-        only.
-        The standard trace masks are given in wxLogTrace()
-        documentation.
-        Finally, the @e wxLog::DoLog() function automatically prepends a time stamp
-        to all the messages. The format of the time stamp may be changed: it can be
-        any string with % specifications fully described in the documentation of the
-        standard @e strftime() function. For example, the default format is
-        "[%d/%b/%y %H:%M:%S] " which gives something like "[17/Sep/98 22:10:16] "
-        (without quotes) for the current date. Setting an empty string as the time
-        format disables timestamping of the messages completely.
-        @note Timestamping is disabled for Visual C++ users in debug builds by
-        default because otherwise it would be impossible to directly go to the line
-        from which the log message was generated by simply clicking in the debugger
-        window on the corresponding error message. If you wish to enable it, please use
-        SetTimestamp() explicitly.
-        AddTraceMask()
-
-        RemoveTraceMask()
-
-        ClearTraceMasks()
-
-        GetTraceMasks()
-
-        IsAllowedTraceMask()
-
-        SetVerbose()
-
-        GetVerbose()
-
-        SetTimestamp()
-
-        GetTimestamp()
-
-        SetTraceMask()
-
-        GetTraceMask()
-
-        SetRepetitionCounting()
-
-        GetRepetitionCounting()
     */
 
 
@@ -554,34 +594,11 @@ public:
     */
     static bool GetVerbose();
 
-    /**
-        The functions in this section work with and manipulate the active log target.
-        The OnLog() is called by the @e wxLogXXX() functions
-        and invokes the DoLog() of the active log target if any.
-        Get/Set methods are used to install/query the current active target and,
-        finally, DontCreateOnDemand() disables the
-        automatic creation of a standard log target if none actually exists. It is
-        only useful when the application is terminating and shouldn't be used in other
-        situations because it may easily lead to a loss of messages.
-        OnLog()
-
-        GetActiveTarget()
-
-        SetActiveTarget()
-
-        DontCreateOnDemand()
-
-        Suspend()
-
-        Resume()
-    */
-
-
     /**
         Returns @true if the @a mask is one of allowed masks for
         wxLogTrace().
-        See also: AddTraceMask(),
+        
-        RemoveTraceMask()
+        See also: AddTraceMask(), RemoveTraceMask()
     */
     static bool IsAllowedTraceMask(const wxString& mask);