Documented code.

ieproxy/CommandLineUI.cpp

@@ -1,6 +1,10 @@
-#include "StdAfx.h"
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
+#include "stdafx.h"
 #include "CommandLineUI.h"
-#include "ieproxy_api.h"
 
 ieproxy::CommandLineUI::CommandLineUI(std::ostream& cout, std::ostream& cerr) :
     _cout(cout), _cerr(cerr), _optDesc("Options")
@@ -30,7 +34,6 @@ ieproxy::CommandLineUI::CommandLineUI(std::ostream& cout, std::ostream& cerr) :
     ;
 }
 
-
 ieproxy::CommandLineUI::~CommandLineUI(void)
 {
 }

ieproxy/CommandLineUI.h

@@ -1,18 +1,40 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
+// Dependancies:
+//   - string.h
+//   - iostream.n
+//   - boost/program_options.hpp
+//
 #pragma once
 #include "stdafx.h"
 #include "ProxySettings.h"
+#include "ieproxy_api.h"
 
 #define VERSION "0.1.1"
 #define YES "Yes"
 #define NO  "No"
-#define IEPROXY "ieproxy"
 #define NOVAL "0"
 
 namespace ieproxy
 {
 
     namespace po = boost::program_options;
 
+    /**
+     * The command-line interface for ieproxy. In most cases it should be used as follows:
+     * 
+     *    #include <iostream>
+     *    #include <CommandLineUI.h>
+     *    
+     *    int main(int argc, char* argv[])
+     *    {
+     *        ieproxy::CommandLineUI cl(std::cout, std::cerr);
+     *        return cl.Run(argc, argv);
+     *    }
+     */
     class CommandLineUI
     {
 
@@ -32,10 +54,26 @@ namespace ieproxy
         void printProxySettings(const ieproxy::ProxySettings& p);
 
     public:
+        /**
+         * Constructs a new CommandLineUI object.
+         * \param cout A reference to an ostream object to which standard output messages will be sent.
+         * \param cerr A reference to an ostream object to which error messages will be sent.
+         */
         CommandLineUI(std::ostream& cout, std::ostream& cerr);
         ~CommandLineUI(void);
 
+        /**
+         * Runs command-line interface for ieproxy.
+         * \param argc The count of command line arguments.
+         * \param argv An array of command line arguments.
+         * \return 2 if there was an retrieving or setting proxy setting, 1 if there was an error parsing the command
+         *           line arguments or 0 if success.
+         */
         int Run(int argc, char* argv[]);
+
+        /**
+         * The ProxySettings object created by Run().
+         */
         const ProxySettings& GetProxySettings() { return _proxySettings; }
 
     };

ieproxy/ProxySettings.cpp

@@ -1,3 +1,8 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
 #include "stdafx.h"
 #include "ProxySettings.h"
 

ieproxy/ProxySettings.h

@@ -1,10 +1,24 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
+// Dependancies:
+//   - string.h
+//   - boost/algorithm/string.hpp
+//
 #pragma once
 #include "stdafx.h"
 
 namespace ieproxy
 {
     namespace algo = boost::algorithm;
 
+    /**
+     * Represents proxy settings for Internet Explorer. Use this instances of this class to retrieve individual
+     * settings after calling ieproxy::api::LoadFromSystem() or to prepare proxy settings and commit them as a batch
+     * using ieproxy::api::SaveToSystem();
+     */
     class ProxySettings
     {
 
@@ -19,34 +33,87 @@ namespace ieproxy
         bool _autoDetect;
 
     public:
+
+        /**
+         * Constructs a new ProxySettings object with default settings.
+         */
         ProxySettings(void);
-        ProxySettings(const char* serverAddress, bool bypassLocal = true, const char* bypassAddresses = "",
-                const char* _autoConfigScriptAddress = "", bool autoDetectSettings = false);
 
-        //~ProxySettings(void);
+        /**
+         * Constructs a new ProxySettings object. 
+         * \param serverAddress The address and port of the proxy server in the form "{server}:{port}" e.g.
+         *                      "cache.example.com:8080". If this argument is an empty string, ProxyEnabled() will
+         *                      return false.
+         * \param bypassLocal If set to true, the proxy server will be bypassed for local addresses.
+         * \param bypassAddresses A list of address for which the proxy server will be bypassed, separated by commas
+         *                        or semicolons.
+         * \param autoConfigScriptAddress The location of the script for automatic proxy configuration If this argument 
+         *                                is an empty string, AutoConfigScriptAddress() will return false.
+         * \param autoDetectSettings Set to true to enable automatic detection of proxy settings.
+         */
+        ProxySettings(const char* serverAddress, bool bypassLocal = true, const char* bypassAddresses = "",
+                const char* autoConfigScriptAddress = "", bool autoDetectSettings = false);
 
+        //! Returns true if use of a proxy server is enabled, otherwise false.
         bool ProxyEnabled() const { return _proxyEnabled; }
+
+        //! Set whether or not a proxy server is used.
+        //! \param value true to enable the user of a proxy server, otherwise false.
         void ProxyEnabled(const bool value) { _proxyEnabled = value; }
 
+        //! Get the address of the proxy server.
         std::string ProxyServer() const { return _proxyServer; }
+
+        //! Set the address and port number of the proxy server.
+        //! \param value The address and port of the proxy server in the form "{server}:{port}" e.g. "cache.example.com:8080".
         void ProxyServer(const char* value) { _proxyServer = value == nullptr ? "" : value; }
+
+        //! Set the address and port number of the proxy server.
+        //! \param value The address and port of the proxy server in the form "{server}:{port}" e.g. "cache.example.com:8080".
         void ProxyServer(std::string value) { ProxyServer(value.c_str()); }
 
+
+        //! Returns true if the proxy server will be bypassed for local addresses, otherwise false.
         bool ProxyBypassLocalAddresses() const { return _proxyBypassLocal; }
+
+        //! Set whether or not the proxy server will be bypassed for local addresses.
+        //! \param value true to bypass local addresses, otherwise false.
         void ProxyBypassLocalAddresses(const bool value) { _proxyBypassLocal = value; }
 
+        //! Returns a semicolon separated list of addresses for which the proxy server will bypassed.
         std::string ProxyBypassAddressList() const { return _proxyBypass; }
+
+        //! Set the list of addresses for which the proxy server will be bypassed.
+        //! \param The list of address, separated by colons or semicolons.
         void ProxyBypassAddressList(const char* value);
+
+        //! Set the list of addresses for which the proxy server will be bypassed.
+        //! \param The list of address, separated by colons or semicolons.
         void ProxyBypassAddressList(std::string value) { ProxyBypassAddressList(value.c_str()); }
 
+        //! Returns true if an automatic configuration script is to be used.
         bool AutoConfigEnabled() const { return _autoConfigEnabled; }
+
+        //! Set whether or not an automatic configuration script is to be used.
+        //! \param value true to enable the user of an automatic configuration script, otherwise false.
         void AutoConfigEnabled(const bool value) { _autoConfigEnabled = value; }
 
+        //! Returns the location of the automatic configuration script
         std::string AutoConfigScriptAddress() const { return _autoConfigScriptAddress; }
+
+        //! Set the location of the automatic configuration script
+        //! \param value The location of the automatic configuration script e.g. "http://wpad/wpad.dat"
         void AutoConfigScriptAddress(const char* value) { _autoConfigScriptAddress = value == nullptr ? "" : value; }
+
+        //! Set the location of the automatic configuration script
+        //! \param value The location of the automatic configuration script e.g. "http://wpad/wpad.dat"
         void AutoConfigScriptAddress(std::string value) { AutoConfigScriptAddress(value.c_str()); }
 
+        //! Return true if automatic detection of proxy settings is enabled.
         bool AutoDetectSettings() const { return _autoDetect; }
+
+        //! Set whether or not to attempt automatic detection of proxy settings.
+        //! \param value true to enable automatic detection of proxy settings, otherwise false.
         void AutoDetectSettings(const bool value) { _autoDetect = value; }
     };
 

ieproxy/ieproxy_api.cpp

@@ -1,3 +1,8 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
 #include "stdafx.h"
 #include "ieproxy_api.h"
 

ieproxy/ieproxy_api.h

@@ -1,14 +1,43 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
+// Dependancies:
+//   - string.h
+//   - windows.h
+//   - wininet.h
+//
 #pragma once
 #include "stdafx.h"
 #include "ProxySettings.h"
 
 namespace ieproxy { namespace api
 {
 
-#define BYPASS_LOCAL_STR "<local>"
+    #define BYPASS_LOCAL_STR "<local>"
 
-char* StringToCharPtr(std::string& s);
-bool LoadFromSystem(ProxySettings& p);
-bool SaveToSystem(const ProxySettings& p);
+    /**
+     * Allocates character array using the contents of the given string object.
+     * \param s The std::string object from which to copy to the newly newly allocated character array
+     * \return A pointer to the newly allocated character array.
+     */
+    char* StringToCharPtr(std::string& s);
+
+    /**
+     * Populates the given ProxySettings object with values retrieved via tine WinINET API.
+     * \param p The ProxySettings object to populate.
+     * \return true if the WinINET API reports that the proxy settings were retrieved successfully or false if there 
+     *              was an error.
+     */
+    bool LoadFromSystem(ProxySettings& p);
+
+    /**
+     * Updates the proxy settings for Internet Explorer using values contained within the given ProxySettings object.
+     * \param The ProxySettings object to retrieve proxy settings from.
+     * \return true if the WinINET API reports that the proxy settings were updated successfully or false if there was
+     *              an error.
+     */
+    bool SaveToSystem(const ProxySettings& p);
 
 } }

ieproxy/main.cpp

@@ -1,6 +1,9 @@
+// Copyright © Dan Stevens 2012
+// 
+// Distributed under the terms of the Boost Software License, Version 1.0.
+// See accompanying file *LICENSE.txt*.
+//
 #include "stdafx.h"
-#include "ieproxy_api.h"
-#include "ProxySettings.h"
 #include "CommandLineUI.h"
 
 int main(int argc, char* argv[])