finished up ofLog docs; hid log level specific objects in index

_documentation/index.markdown

@@ -158,12 +158,12 @@ __advanced: true__
 
 
 ###ofLogError###
-__visible: true__
+__visible: false__
 __advanced: false__
 
 
 ###ofLogWarning###
-__visible: true__
+__visible: false__
 __advanced: false__
 
 
@@ -190,7 +190,7 @@ __advanced: false__
 
 
 ###ofLogNotice###
-__visible: true__
+__visible: false__
 __advanced: false__
 
 
@@ -216,7 +216,7 @@ __advanced: false__
 
 
 ###ofLogVerbose###
-__visible: true__
+__visible: false__
 __advanced: false__
 
 
@@ -246,7 +246,7 @@ __advanced: false__
 
 
 ###ofLogFatalError###
-__visible: true__
+__visible: false__
 __advanced: false__
 
 

_documentation/utils/ofLog.markdown

@@ -7,34 +7,87 @@ ofLog provides an interface for writing text output from your app. It's basicall
 
 Sometimes you want to be able to see when something has happened inside the code, but don't need to draw something visually. Oftentimes it's more then enough to print out the state of a few variables when debugging. Other times you need to know if a crash happened while your app was running somewhere, so you log messages and variables to a file you can read after the program crashes.
 
-You can also set the logging level so only messages above a certain priority are shown. This is useful if you want see lots of messages when debugging, but then set a higher level so only warnings and errors appear for users. See [ofSetLogLevel()](./ofLog_functions.htm) for more detail.
+####Log Levels
+
+You can also set the logging level so only messages above a certain priority are shown. This is useful if you want see lots of messages when debugging, but then set a higher level so only warnings and errors appear for users. See [ofSetLogLevel(logLevel)](./ofLog.html#functions) for more detail.
+
+Log levels are (in order of priority):
+
+	OF_LOG_VERBOSE
+	OF_LOG_NOTICE
+	OF_LOG_WARNING
+	OF_LOG_ERROR
+	OF_LOG_FATAL_ERROR
+	OF_LOG_SILENT
+
+**Note**: `OF_LOG_SILENT` is a special value which disables **all** messages.
+
+####Usage
 
 There are 2 ways you can use ofLog:
 
-1. as a function taking a message
-2. as a stream using the << stream operator
+####Functional: as a function taking a message
 
-~~~~{.cpp}
 
-// FUNCTIONAL
+~~~~{.cpp}
 
-// send a single string message
+// send a single string message, setting the log level
 ofLog(OF_LOG_NOTICE, "the number is " + ofToString(10));
 
 // the legacy printf style
 ofLog(OF_LOG_NOTICE, "the number is %d", 10); 
 
-// STREAM
+~~~~
+
+See [ofLog(logLevel, &message) & ofLog(logLevel, format*, …)](./ofLog.html#methods) for more details.
+
+####Stream: as a stream using the << stream operator
 
-// the stream style
+~~~~{.cpp}
+
+// the stream style, setting the log level
 ofLog(OF_LOG_NOTICE) << "the number is " << 10;
 
-// there are also log level specific stream objects
-ofLogNotice() << "the number is " << 10;
+// this is the same as the last line, but only sends at log level notice
+ofLog() << "the number is " << 10;
+
+// there are also log level specific stream objects,
+// one for each level except OF_LOG_SILENT
+ofLogVerbose() << "a verbose print"
+ofLogNotice() << "a regular notice print";
+ofLogWarning() << "uh oh, a warning";
+ofLogError() << "oh no, an error occurred!";
+ofLogFatalError() << "accckkk, a fatal error!!";
 
 ~~~~
 
-For log redirection see ofLogToFile(), ofLogToConsole(), & ofSetLoggerChannel() in the [ofLog functions](./ofLog_functions.htm).
+**Note**: The log level specific stream objects also take a string argument for the "module". A module is a string that is added to the beginning of the log line and can be used to separate logging messages by setting an independent log level for **that module only**. This module-specific log level has no effect on other modules. See [ofSetLogLevel(module, logLevel)](./ofLog.html#functions) for more detail.
+
+~~~~{.cpp}
+
+// log to a module called "Hello"
+ofLogWarning("Hello") << "a warning print";
+
+~~~~
+
+**Warning**: It is important to understand that the log level specific stream objects take the module name as an argument and the log messages via the << operator. Putting your message as a string argument inside the parentheses uses that message as a *module* and so nothing will be printed:
+
+~~~~{.cpp}
+
+// this prints a warning message
+ofLogWarning() << "a warning print";
+
+// !!! this does not print a message as the string "a warning print" is the module argument !!!
+ofLogWarning("a warning print");
+
+// this prints a warning message to the "Hello" module
+ofLogWarning("Hello") << "a warning print";
+
+~~~~
+
+####Log Message Redirection
+
+Last, it's useful to be able to record log messages to a file or send them to a custom destination. For log redirection see ofLogToFile(), ofLogToConsole(), & ofSetLoggerChannel() in the [ofLog functions](./ofLog.html#functions).
 
 ##Methods
 
@@ -71,9 +124,9 @@ ofLog() << "a string" << 100 << 20.234f;
 
 ~~~~
 
-The log level is explicitly OF_LOG_NOTICE.
+The log level is explicitly `OF_LOG_NOTICE`.
 
-See [ofSetLogLevel()](./ofLog_functions.htm) for more info on log levels.
+See [ofSetLogLevel(logLevel)](./ofLog.html#functions) for more info on log levels.
 
 <!----------------------------------------------------------------------------->
 
@@ -106,9 +159,25 @@ ofLog(OF_LOG_WARNING) << "a string" << 100 << 20.234f;
 
 ~~~~
 
-See the derived convenience classes for specific log levels: `ofLogVerbose`, `ofLogNotice`, `ofLogWarning`, `ofLogError`, & `ofLogFatalError`.
+You can use the derived convenience classes as an alternative for specific log levels: 
 
-See [ofSetLogLevel()](./ofLog_functions.htm) for more info on log levels.
+	ofLogVerbose()
+	ofLogNotice()
+	ofLogWarning()
+	ofLogError()
+	ofLogFatalError()
+
+~~~~{.cpp}
+
+// set the log level
+ofLog(OF_LOG_WARNING) << "a string" << 100 << 20.234f;
+
+// this is the same as above
+ofLogWarning() << "a string" << 100 << 20.234f;
+
+~~~~
+
+See [ofSetLogLevel()](./ofLog.html#functions) for more info on log levels.
 
 <!----------------------------------------------------------------------------->
 
@@ -134,16 +203,17 @@ _description: _
 
 Logs a string at a specific log level.
 
-The string message can be concatenated using the ofToString() conversion function in [ofUtils](./ofUtils_functions.htm):
+The string message can be concatenated using the ofToString() conversion function in [ofUtils](./ofUtils.html#functions):
 
 ~~~~{.cpp}
 
 // build a single string message
-ofLog(OF_LOG_NOTICE, "the number is " + ofToString(10) + " and I have a float too " + ofToString(123.45f));
+ofLog(OF_LOG_NOTICE, "the number is " 
++ ofToString(10) + " and I have a float too " + ofToString(123.45f));
 
 ~~~~
 
-See [ofSetLogLevel()](./ofLog_functions.htm) for more info on log levels.
+See [ofSetLogLevel(logLevel)](./ofLog.html#functions) for more info on log levels.
 
 <!----------------------------------------------------------------------------->
 
@@ -167,6 +237,41 @@ _advanced: False_
 
 _description: _
 
+Logs a message at a specific log level using the printf interface.
+
+The message is built using the formatting from the C printf function and can be used as a direct replacement. Essentially, the second argument is a string with special formatting specifiers starting with '%' that specify where the following variables go in the message. You can have as many variables as you want following the logLevel and format string, but there must be a % specifier for each subsequent variable.
+
+For quick reference, here are a few of the most useful formatting specifiers:
+
+* **%d**: integer number, 123
+* **%f**: floating point number, 123.45
+* **%s**: a C string ([null terminated](http://en.wikipedia.org/wiki/Null-terminated_string)); this is not a C++ string, use [string::c_str()](http://www.cplusplus.com/reference/string/string/c_str/) to get a C string from a C++ string
+* **%c**: a single character
+* **%x**: unsigned integer as a [hexidecimal](http://en.wikipedia.org/wiki/Hexadecimal) number; 'x' uses lower-case letters and 'X' uses upper-case
+* **%%**: prints a '%' character
+
+The specifier should match the variable type as it is used to tell the function how to convert that primitive type (int, float, character, etc) into a string.
+
+For instance, let's say we want to print two messages, a salutation and the value of an int, a float, and a string variable:
+
+~~~~{.cpp}
+
+// print a simple message with no variables
+ofLog(OF_LOG_WARNING, "welcome to the jungle);
+
+// our variables
+float fun = 11.11;
+int games = 100;
+string theNames = "Dan, Kyle, & Golan";
+
+// print a message with variables, sets the message format in the format string
+ofLog(OF_LOG_NOTICE, "we've got %d & %f, we got everything you want honey, we know %s", fun, games, theNames.c_str());
+
+~~~~
+
+Note: `theNames.c_str()` returns a C string from theNames which is a C++ string object.
+
+There are other formatting options such as setting the decimal precision of float objects and the forward padding of numbers (i.e. 0001 instead of 1). See the [Wikipedia printf format string article](http://en.wikipedia.org/wiki/Printf_format_string) for more detailed information.
 
 <!----------------------------------------------------------------------------->
 
@@ -237,7 +342,7 @@ _description: _
 
 Sets the logging channel that receives log messages. This is analogous to ofSetLoggerChannel().
 
-See ofSetLoggerChannel() for more detail.
+See [ofSetLoggerChannel()](./ofLog.html#functions) for more detail.
 
 <!----------------------------------------------------------------------------->
 

_documentation/utils/ofLog_functions.markdown

@@ -2,9 +2,7 @@
 
 ##Description
 
-
-
-
+The ofLog functions provide control of the global logging interface. You can set the overall logging level in order to filter what messages you want to see when debugging or releasing an application. Log messages can also be directed to a file or a custom destination.
 
 <!----------------------------------------------------------------------------->
 
@@ -38,7 +36,7 @@ logLevel values are (in order of priority):
 	OF_LOG_FATAL_ERROR
 	OF_LOG_SILENT
 
-Following priority, setting a log level of OF_LOG_ERROR, means only error & fatal error messages will be printed. Conversely, setting OF_LOG_VERBOSE means **all** log level messages will be printed.
+Following priority, setting a log level of `OF_LOG_ERROR`, means only error & fatal error messages will be printed. Conversely, setting `OF_LOG_VERBOSE` means **all** log level messages will be printed.
 
 Here's a code example:
 
@@ -60,9 +58,9 @@ ofLogVerbose() << "a verbose print";	// this doesn't
 
 ~~~~
 
-The default log level is OF_LOG_NOTICE.
+The default log level is `OF_LOG_NOTICE`.
 
-OF_LOG_SILENT is a special value which disables **all** messages.
+`OF_LOG_SILENT` is a special value which disables **all** messages.
 
 <!----------------------------------------------------------------------------->
 
@@ -85,11 +83,12 @@ _advanced: True_
 
 _description: _
 
-Sets the logging level for a particular "module". A module is a string that is added to the beginning of the log line and can be used to separate logging messages by setting an independent log level for **this module only**. This module-specific log level has no effect on other modules.
+Sets the logging level for a particular "module". A module is a string that is added to the beginning of the log line and can be used to separate logging messages by setting an independent log level for **that module only**. This module-specific log level has no effect on other modules.
 
-For instance, let's say you have an object called "Hello". If you set the log level for "Hello" to OF_LOG_ERROR, no messages to "Hello" with a level below OF_LOG_ERROR will print. However, this has no effect on regular logging messages:
+For instance, let's say you have an object called "Hello". If you set the log level for "Hello" to `OF_LOG_ERROR`, no messages to "Hello" with a level below `OF_LOG_ERROR` will print. However, this has no effect on regular logging messages:
 
 ~~~~{.cpp}
+
 // "Hello" starts at log level notice
 
 // log to the "Hello" module
@@ -111,14 +110,27 @@ ofLogNotice() << "a test print";			// still prints, not affected by "Hello"
 
 ~~~~
 
-The default log level for modules is OF_LOG_NOTICE.
+The default log level for modules is `OF_LOG_NOTICE`.
 
 The default module when logging without setting the module is "OF". So setting the log level for "OF" to OF_LOG_SILENT will disable all non-module log messages.
 
 See ofSetLogLevel for the log level values. 
 
 Note: ofLog() itself cannot accept a module variable. You must use one of the specific log level classes: `ofLogVerbose`, `ofLogNotice`, `ofLogWarning`, `ofLogError`, & `ofLogFatalError`.
 
+~~~~{.cpp}
+
+// this prints a warning message
+ofLogWarning() << "a warning print";
+
+// !!! This does not print a message as the string "a warning print" is the module argument !!!
+ofLogWarning("a warning print");
+
+// this prints a warning message to the "Hello" module
+ofLogWarning("Hello") << "a warning print";
+
+~~~~
+
 <!----------------------------------------------------------------------------->
 
 ###ofLogLevel ofGetLogLevel()
@@ -262,7 +274,7 @@ ofLog() << "The current log level is " << ofGetLogLevelName(currentLevel);
 
 ~~~~
 
-See ofSetLogLevel for the log level values. 
+See [ofSetLogLevel(logLevel)](./ofLog.html#functions) for the log level values. 
 
 <!----------------------------------------------------------------------------->
 
@@ -287,7 +299,7 @@ _description: _
 
 Enable logging to a file instead of the console.
 
-Set the path and name of the log file and it will be created if it doesn't exist. If it does exist, it will be overwritten unless you set **append** to true, whereas new lines will be added to the bottom of the file.
+Set the path and name of the log file and it will be created if it doesn't exist. If it does exist, it will be overwritten unless you set *append* to true, whereas new lines will be added to the bottom of the file.
 
 ~~~~{.cpp}
 
@@ -328,7 +340,11 @@ _description: _
 
 Enable logging to the console instead of a file.
 
-Log messages will be printed to the console (CMD on Win, Terminal/Xcode debug window on Mac, xterm/gnome-terminal etc on Linux). 
+Log messages will be printed to the console:
+
+* Windows: CMD Prompt on Windows
+* Mac: Terminal or the Xcode debug window (when debugging)
+* Linux: xterm, gnome-terminal, etc
 
 Console logging is enabled by default.