From e1cbc6fee6c8972e97e8ad4fac69ffded48eb3d7 Mon Sep 17 00:00:00 2001
From: Luboš Luňák <l.lunak@suse.cz>
Date: Fri, 27 Jan 2012 17:45:07 +0100
Subject: add a file to list of known SAL_INFO areas

---
 sal/inc/sal/log-areas.dox | 21 +++++++++++++++++++++
 sal/inc/sal/log.hxx       | 29 ++++++++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)
 create mode 100644 sal/inc/sal/log-areas.dox

(limited to 'sal')

diff --git a/sal/inc/sal/log-areas.dox b/sal/inc/sal/log-areas.dox
new file mode 100644
index 000000000000..9dfe1762f623
--- /dev/null
+++ b/sal/inc/sal/log-areas.dox
@@ -0,0 +1,21 @@
+/**
+@page sal_log_areas SAL debug areas
+ 
+@short List and description of areas for the SAL debug macros
+ 
+This is a list of areas that are used by the SAL_INFO family of macros.
+See @ref sal_log "basic log functionality" for details about this functionality.
+
+If you need use a debug area in some code, first check this list and use
+the appropriate area if it exists. This list is not definite, if you need
+a new area, use it and add it to the list in the proper section with an explanation.
+
+This list should give you an overview of which areas to enable when debugging
+certain functionality.
+
+@section Writer
+
+@li sw.uno - Writer's UNO interfaces
+@li sw.ww8 - .doc/.docx export filter, .doc import filter (not writerfilter)
+
+*/
diff --git a/sal/inc/sal/log.hxx b/sal/inc/sal/log.hxx
index ec1fdfa61830..6a2a17c81a1c 100644
--- a/sal/inc/sal/log.hxx
+++ b/sal/inc/sal/log.hxx
@@ -180,7 +180,10 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
     (dynamic_cast< ::std::ostringstream & >(::std::ostringstream() << stream). \
      str())
 
-/** Basic logging functionality.
+/**
+    @page sal_log Basic logging functionality.
+
+    @short Macros for logging.
 
     SAL_INFO(char const * area, expr),
     SAL_INFO_IF(bool condition, char const * area, expr),
@@ -214,6 +217,8 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
 
       <segment> ::= [0-9a-z]+
 
+    For a list of areas used see @ref sal_log_areas "SAL debug areas".
+
     Whether these macros generate any log output is controlled in a two-stage
     process.
 
@@ -259,27 +264,49 @@ inline char const * unwrapStream(SAL_UNUSED_PARAMETER StreamIgnore const &) {
     change.  The log output is printed to stderr without further text encoding
     conversion.
 
+    @see @ref sal_log_areas
+
     @attention For now, this functionality should only be used internally within
     LibreOffice. It may change again in a future version.
 
     @since LibreOffice 3.5
 */
 
+/**
+  Produce log entry from stream in the given log area.
+
+  See @ref sal_log "basic logging functionality" for details.
+*/
 #define SAL_INFO(area, stream) \
     SAL_DETAIL_LOG_STREAM( \
         SAL_DETAIL_ENABLE_LOG_INFO, ::SAL_DETAIL_LOG_LEVEL_INFO, area, \
         SAL_WHERE, stream)
 
+/**
+  Produce log entry from stream in the given log area if condition is true.
+
+  See @ref sal_log "basic logging functionality" for details.
+*/
 #define SAL_INFO_IF(condition, area, stream)  \
     SAL_DETAIL_LOG_STREAM( \
         SAL_DETAIL_ENABLE_LOG_INFO && (condition), \
         ::SAL_DETAIL_LOG_LEVEL_INFO, area, SAL_WHERE, stream)
 
+/**
+  Produce warning entry from stream in the given log area.
+
+  See @ref sal_log "basic logging functionality" for details.
+*/
 #define SAL_WARN(area, stream) \
     SAL_DETAIL_LOG_STREAM( \
         SAL_DETAIL_ENABLE_LOG_WARN, ::SAL_DETAIL_LOG_LEVEL_WARN, area, \
         SAL_WHERE, stream)
 
+/**
+  Produce warning entry from stream in the given log area if condition is true.
+
+  See @ref sal_log "basic logging functionality" for details.
+*/
 #define SAL_WARN_IF(condition, area, stream)   \
     SAL_DETAIL_LOG_STREAM( \
         SAL_DETAIL_ENABLE_LOG_WARN && (condition), \
-- 
cgit