Document the fact that LLDB_LOG uses llvm::format_providers

[jingham]

Summary

This is a handy and powerful addition to the logging system, but not at all discoverable.

This is a trivial patch, but since I don't actually know much about these formatters I put it up for review in case there's more useful detail to add or people can think of a better place to put this.

[labath]

I think this is the best place to put that comment. Your lines are longer than 80 chars though. :)

[jingham]

Yeah, I didn't want to bother with formatting in case there were suggestions on content. I checked in a version that's correctly truncated.

lldb/trunk/include/lldb/Utility/Log.h

private:
   static void DisableLoggingChild();
 
   Log(const Log &) = delete;
   void operator=(const Log &) = delete;
 };
 
 } // namespace lldb_private
 
+/// The LLDB_LOG* macros defined below are the way to emit log messages.
+///
+/// Note that the macros surround the arguments in a check for the log
+/// being on, so you can freely call methods in arguments without affecting
+/// the non-log execution flow.
+///
+/// If you need to do more complex computations to prepare the log message
+/// be sure to add your own if (log) check, since we don't want logging to
+/// have any effect when not on.
+///
+/// However, the LLDB_LOG macro uses the llvm::formatv system (see the
+/// ProgrammersManual page in the llvm docs for more details).  This allows
+/// the use of "format_providers" to auto-format datatypes, and there are
+/// already formatters for some of the llvm and lldb datatypes.
+///
+/// So if you need to do non-trivial formatting of one of these types, be
+/// sure to grep the lldb and llvm sources for "format_provider" to see if
+/// there is already a formatter before doing in situ formatting, and if
+/// possible add a provider if one does not already exist.
+
 #define LLDB_LOG(log, ...)                                                     \
   do {                                                                         \
     ::lldb_private::Log *log_private = (log);                                  \
     if (log_private)                                                           \
       log_private->Format(__FILE__, __func__, __VA_ARGS__);                    \
   } while (0)
 
 #define LLDB_LOGF(log, ...)                                                    \