Merge pull request #93 from Flamefire/args_docu

Make the behavior of the class args clearer

doc/main.dox

@@ -222,9 +222,9 @@ This very simple and straightforward approach helps writing Unicode aware progra
 Watch the use of \c boost::nowide::args, \c boost::nowide::ifstream and \c boost::nowide::cerr/cout.
 On Non-Windows it does nothing, but on Windows the following happens:
 
-- \c boost::nowide::args uses the Windows API to retrieve UTF-16 arguments, converts them to UTF-8
-and replaces the original \c argv (and optionally \c env) to point to those, internally stored
-UTF-8 strings.
+- \c boost::nowide::args retrieves UTF-16 arguments from the Windows API, converts them to UTF-8,
+and temporarily replaces the original \c argv (and optionally \c env) with pointers to those internally stored
+UTF-8 strings for the lifetime of the instance.
 - \c boost::nowide::ifstream converts the passed filename (which is now valid UTF-8) to UTF-16
 and calls the Windows Wide API to open the file stream which can then be used as usual.
 - Similarily \c boost::nowide::cerr and \c boost::nowide::cout use an underlying stream buffer

include/boost/nowide/args.hpp

@@ -33,20 +33,29 @@ namespace nowide {
 #else
 
     ///
-    /// \brief args is a class that fixes standard main() function arguments and changes them to UTF-8 under
-    /// Microsoft Windows.
+    /// \brief \c args is a class that temporarily replaces standard main() function arguments with their
+    /// equal, but UTF-8 encoded values under Microsoft Windows for the lifetime of the instance.
     ///
     /// The class uses \c GetCommandLineW(), \c CommandLineToArgvW() and \c GetEnvironmentStringsW()
-    /// in order to obtain the information. It does not relate to actual values of argc,argv and env
-    /// under Windows.
+    /// in order to obtain Unicode-encoded values.
+    /// It does not relate to actual values of argc, argv and env under Windows.
     ///
-    /// It restores the original values in its destructor
+    /// It restores the original values in its destructor (usually at the end of the \c main function).
     ///
     /// If any of the system calls fails, an exception of type std::runtime_error will be thrown
     /// and argc, argv, env remain unchanged.
     ///
-    /// \note the class owns the memory of the newly allocated strings
+    /// \note The class owns the memory of the newly allocated strings.
+    /// So you need to keep it alive as long as you use the values.
     ///
+    /// Usage:
+    /// \code
+    /// int main(int argc, char** argv, char** env) {
+    ///   boost::nowide::args _(argc, argv, env); // Note the _ as a "don't care" name for the instance
+    ///   // Use argv and env as usual, they are now UTF-8 encoded on Windows
+    ///   return 0; // Memory held by args is released
+    /// }
+    /// \endcode
     class args
     {
     public:
@@ -69,7 +78,7 @@ namespace nowide {
             fix_env(env);
         }
         ///
-        /// Restore original argc,argv,env values, if changed
+        /// Restore original argc, argv, env values, if changed
         ///
         ~args()
         {