FreeLists / haiku-doc / [haiku-doc] System logging

["Alan Smale" <ajsmale@xxxxxxxxx>]

Hi guys,

I have performed some changes/proofreading to the system logging
documentation.

Can you check through and see whether it's acceptable.

Changes:

- Added system logging overview (Reworked from Axel's Haiku article)
- Added parameter lists to functions
- Reworked text to fit into the Doxygen structure

I'm not sure if ultimately the file names need renaming, so I've not done
that.

Cheers

Alan

Index: support_intro.dox
===================================================================
--- support_intro.dox   (revision 21323)
+++ support_intro.dox   (working copy)
@@ -33,6 +33,7 @@
   - BStopWatch
   - \ref support_globals "Global functions"
   - \ref TypeConstants.h "Common types and constants"
+  - \ref support_system-logging "System logging"
   - Error codes for all kits
 */
 

Index: syslog.dox
===================================================================
--- syslog.dox  (revision 21323)
+++ syslog.dox  (working copy)
@@ -1,12 +1,14 @@
 /*
- * Copyright 2007, Haiku, Inc. All Rights Reserved.
+ * Copyright 2007 Haiku Inc. All rights reserved.
  * Distributed under the terms of the MIT License.
  *
- * Documentation written by:
+ * Authors:
  *   Axel Dörfler
  *   Niels Sascha Reedijk <niels.reedijk@xxxxxxxxx>
+ * Proofreaders:
+ *   Alan Smale <ajsmale@xxxxxxxxx>
  * Corresponds to:
- *   /trunk/headers/posix/syslog.h rev 6684
+ *   /trunk/headers/posix/syslog.h rev 11769
  */
 
 /*!
@@ -15,76 +17,115 @@
   \ingroup libroot
   \brief System logging capabilities
 
-  The functions described here are interacting with the syslog_daemon, a server
-  that provides the system logging capabilities.
-  The log can be found in /var/log/syslog.
+  The functions described here interact with the syslog_daemon, a server that
+  provides the system logging capabilities. The log output can be found in
+  /var/log/syslog.
 */
 
-/*! 
+/*!
   \fn void closelog(void)
-  \brief Closes the current log session
+  \brief Closes the current log thread session
+
+  Frees all associated data. The next call to the syslog service will start a
+  new session, and will inherit the team log options at that point again.
 */
 
-/*! 
+/*!
   \fn void openlog(const char *ident, int options, int facility)
-  \brief Starts a log session, and sets some output options
+  \brief Starts a log session, and sets the output options
 
-  Like openlog_thread() this function defines the log session in thread 
context; the
-  global options set by openlog_team() are not affected by this function.
+  Like openlog_thread() this function defines the log session in thread 
context;
+  the global options set by openlog_team() are not affected by this function.
+
+  \param ident The identification string that prepends every message from your
+  team.
+  \param options Allows you to set several logging options.
+  \param facility Determines from what facility your message has been sent.
 */
 
-/*! 
+/*!
   \fn int setlogmask(int priorityMask)
-  \brief sets the logging priority mask
+  \brief Sets the log priority mask
+
+  \param priorityMask Mask of message priorities.
+  \return Previous log priority mask
 */
 
-/*! 
+/*!
   \fn void syslog(int priority, const char *message, ...)
-  \brief sends a message to the system log
+  \brief Sends a message to the system log
+
+  \param priority Priority of message.
+  \param message Message to display.
 */
 
-/*! 
+/*!
   \fn void closelog_team(void)
   \brief Closes the log
 */
 
-/*! 
+/*!
   \fn void openlog_team(const char *ident, int logopt, int facility)
   \brief Starts a log session, and sets some output options
 
   This function defines the team-wide logging options. Thread local sessions
   started with openlog() or openlog_thread() will inherit the options of the
   global session.
+
+  \param ident The identification string that prepends every message from your
+  team.
+  \param logopt Allows you to set several logging options.
+  \param facility Determines from what facility your message has been sent.
 */
 
-/*! 
+/*!
   \fn void log_team(int priority, const char *message, ...)
-  \brief sends a message to the system log
+  \brief Sends a message to the system log
+
+  \param priority Priority of message.
+  \param message Message to display.
 */
 
-/*! 
+/*!
   \fn int setlogmask_team(int priorityMask)
-  \brief sets the logging priority mask
+  \brief Sets the log priority mask
+
+  \param priorityMask Mask of message priorities.
+  \return Previous log priority mask
 */
 
-/*! 
+/*!
   \fn void closelog_thread(void)
-  \brief Closes the log
+  \brief Closes the current log thread session
+
+  Frees all associated data. The next call to the syslog service will start a
+  new session, and will inherit the team log options at that point again.
 */
 
-/*! 
+/*!
   \fn void openlog_thread(const char *ident, int logopt, int facility)
-  \brief Starts a log session, and sets some output options
+  \brief Starts a log session, and sets the output options
+
+  \param ident The identification string that prepends every message from your
+  team.
+  \param logopt Allows you to set several logging options.
+  \param facility Determines from what facility your message has been sent.
 */
 
-/*! 
+/*!
   \fn void log_thread(int priority, const char *message, ...)
-  \brief sends a message to the system log
+  \brief Sends a message to the system log
+
+  \param priority Priority of message.
+  \param message Message to display.
 */
 
-/*! 
+/*!
   \fn int setlogmask_thread(int priorityMask)
-  \brief sets the logging priority mask
+  \brief Sets the log priority mask
+
+  \param priorityMask Mask of message priorities.
+  \return Previous log priority mask
 */
 
 /*!
@@ -93,38 +134,38 @@
 
 //! @{
 
-/*! 
+/*!
   \def LOG_PID
   \brief Log the process (thread/team) ID with each message 
 */
 
-/*! 
+/*!
   \def LOG_CONS
   \brief Log to the system console on error
 */
 
-/*! 
+/*!
   \def LOG_ODELAY
   \brief Delay open until syslog() is called 
 */
 
-/*! 
+/*!
   \def LOG_NDELAY
   \brief Connect to the syslog daemon immediately 
 */
 
-/*! 
+/*!
   \def LOG_SERIAL
   \brief Dump to serial output as well.
   \attention This is not yet implemented
 */
 
-/*! 
+/*!
   \def LOG_PERROR
   \brief Dump to stderr as well
 */
 
-/*! 
+/*!
   \def LOG_NOWAIT
   \brief Do not wait for child processes
 */
@@ -137,44 +178,44 @@
 
 //! @{
 
-/*! 
+/*!
   \def LOG_KERN
   \brief Reserved for messages generated by the kernel.
 */
 
-/*! 
+/*!
   \def LOG_USER
   \brief Reserved for messages generated by user processes.
 */
 
 /*!
   \def LOG_MAIL
-  \brief Standard (?) POSIX facility for messages by the mailing daemon.
+  \brief Standard POSIX facility for messages by the mailing daemon.
 */
 
-/*! 
+/*!
   \def LOG_DAEMON
-  \brief Standard POSIX (?) facility for messages by daemons (and Haiku 
servers).
+  \brief Standard POSIX facility for messages by daemons (and Haiku servers).
 */
 
-/*! 
+/*!
   \def LOG_AUTH
-  \brief Standard POSIX facility(?) for messages by the authentication 
services.
+  \brief Standard POSIX facility for messages by the authentication services.
 */
 
-/*! 
+/*!
   \def LOG_SYSLOG
   \brief Reserved for messages generated by the syslog daemon.
 */
 
-/*! 
+/*!
   \def LOG_LPR
   \brief Reserved for messages generated by the UNIX lpr printing tool.
 */
 
-/*! 
+/*!
   \def LOG_NEWS
-  \brief Reserved for messages generated by something UNIXy that does 
something with NEWS.
+  \brief Reserved for messages generated by the UNIX news system.
 */
 
 /*!
@@ -187,49 +228,49 @@
   \brief Reserved for messages generated by the CRON daemon.
 */
 
-/*! 
+/*!
   \def LOG_AUTHPRIV
-  \brief Reserved for private (?) messages that relate to authentication.
+  \brief Reserved for private messages that relate to authentication.
 */
 
 /*!
   \def LOG_LOCAL0
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
 /*!
   \def LOG_LOCAL1
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL2
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL3
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL4
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL5
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL6
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
-/*! 
+/*!
   \def LOG_LOCAL7
-  \brief Use this for local use.
+  \brief Reserved for local use.
 */
 
 //! @}
@@ -240,54 +281,54 @@
 
 //! @{
 
-/*! 
+/*!
   \def LOG_EMERG
   \brief A panic condition
 */
 
-/*! 
+/*!
   \def LOG_PANIC
   \brief An alias for LOG_EMERG
 */
 
-/*! 
+/*!
   \def LOG_ALERT
   \brief A condition to that should be corrected immediately
 */
 
-/*! 
+/*!
   \def LOG_CRIT
-  \brief Critical conditions like hard drive errors
+  \brief Critical conditions such as hard drive errors
 */
 
-/*! 
+/*!
   \def LOG_ERR
   \brief Errors
 */
 
-/*! 
+/*!
   \def LOG_WARNING
   \brief Warnings
 */
 
-/*! 
+/*!
   \def LOG_NOTICE
   \brief Notices, instructions on how to use certain configuration options.
 */
 
-/*! 
+/*!
   \def LOG_INFO
-  \brief Information, like versions and so.
+  \brief Informational messages.
 */
 
-/*! 
+/*!
   \def LOG_DEBUG
   \brief Debug information.
 */\
 
 //! @}
 
-/*! 
+/*!
   \def LOG_MASK
-  \brief Converts a priority definition for use in setlogmask()
-*/
\ No newline at end of file
+  \brief Converts a priority definition into a mask for use with setlogmask()
+*/