From 883ce6fcbfe344859ddb41eefa043930067405dd Mon Sep 17 00:00:00 2001
From: Darryl Pogue <dvpdiner2@gmail.com>
Date: Tue, 27 Mar 2012 21:32:02 -0700
Subject: [PATCH] Doxygen plNetAddress to make it less confusing.

---
 .../NucleusLib/pnNetCommon/plNetAddress.cpp   |  12 --
 .../NucleusLib/pnNetCommon/plNetAddress.h     | 113 +++++++++++++++++-
 2 files changed, 111 insertions(+), 14 deletions(-)

diff --git a/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.cpp b/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.cpp
index 52ad0ae0..6784dfe8 100644
--- a/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.cpp
+++ b/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.cpp
@@ -107,11 +107,6 @@ uint32_t plNetAddress::GetHost() const
     return fAddr.sin_addr.s_addr;
 }
 
-uint32_t plNetAddress::GetHostLE() const
-{
-    return ntohl(fAddr.sin_addr.s_addr);
-}
-
 plString plNetAddress::GetHostWithPort() const
 {
     plStringStream ss;
@@ -133,13 +128,6 @@ bool plNetAddress::SetHost(uint32_t addr)
     return true;
 }
 
-bool plNetAddress::SetHostLE(uint32_t addr)
-{
-    fAddr.sin_addr.s_addr = htonl(addr);
-    fAddr.sin_family = AF_INET;
-    return true;
-}
-
 plString plNetAddress::AsString() const
 {
     plStringStream ss;
diff --git a/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.h b/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.h
index 645d7fe0..bf699251 100644
--- a/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.h
+++ b/Sources/Plasma/NucleusLib/pnNetCommon/plNetAddress.h
@@ -68,46 +68,155 @@ You can contact Cyan Worlds, Inc. by email legal@cyan.com
 
 typedef sockaddr_in  AddressType;
 
+/**
+ * A class representing a network address endpoint, as a pair of host address
+ * and port number.
+ *
+ * Internally, this class stores the network address using the sockaddr_in
+ * structure, but provides methods to transparently get and set the host
+ * address and port.
+ */
 class plNetAddress
 {
     // fAddr must be first field
     AddressType     fAddr;
 
 public:
+    /**
+     * Initializes an empty network address.
+     * All the fields of the sockaddr will be zeroed.
+     */
     plNetAddress();
+
+    /**
+     * Initializes a new network address from the given IPv4 address and port
+     * number.
+     *
+     * @param addr The IPv4 address as a 32-bit network byte order integer.
+     * @param port The port number as a 16-bit host order integer.
+     */
     plNetAddress(uint32_t addr, uint16_t port);
+
+    /**
+     * Initializes a new network address from the given hostname and port
+     * number.
+     *
+     * @param addr The DNS hostname of the host.
+     * @param port The port number as a 16-bit host order integer.
+     */
     plNetAddress(const char* addr, uint16_t port);
+
     virtual ~plNetAddress(){}
 
     bool operator==(const plNetAddress& other) const {
         return (GetHost() == other.GetHost()) && (GetPort() == other.GetPort());
     }
+
     bool operator!=(const plNetAddress& other) const {
         return !(*this == other);
     }
 
+    /**
+     * Clears the address and zeros out the sockaddr fields.
+     */
     void Clear();
 
+    /**
+     * Sets the address to INADDR_ANY for binding to any host.
+     */
     bool SetAnyAddr();
+
+    /**
+     * Sets the port number to 0 to allow binding to any port.
+     */
     bool SetAnyPort();
 
+    /**
+     * Gets the port number of the host.
+     *
+     * @return The host port number.
+     */
     uint16_t GetPort() const;
+
+    /**
+     * Sets the port number of the host.
+     *
+     * @param port The port number in host byte order.
+     */
     bool SetPort(uint16_t port);
 
+    /**
+     * Gets the IPv4 address of the host as a 32-bit integer in network byte
+     * order (big endian).
+     *
+     * @return The IPv4 host address.
+     */
     uint32_t GetHost() const;
-    uint32_t GetHostLE() const;
+
+    /**
+     * Sets the IPv4 address of the host from a DNS name.
+     *
+     * @param hostname The DNS name of the host.
+     */
     bool SetHost(const char* hostname);
+
+    /**
+     * Sets the IPv4 address of the host from an unsigned 32-bit integer in
+     * network byte order (big endian).
+     *
+     * @param ip4addr The host IPv4 address in network byte order.
+     */
     bool SetHost(uint32_t ip4addr);
-    bool SetHostLE(uint32_t addr);
 
+    /**
+     * Retrieves the internal address type.
+     *
+     * @return A constant sockaddr_in.
+     */
     const AddressType& GetAddressInfo() const { return fAddr; }
+
+    /**
+     * Retrieves the internal address type.
+     *
+     * @return A sockaddr_in.
+     */
     AddressType& GetAddressInfo() { return fAddr; }
 
+    /**
+     * Returns the IPv4 address of the host as a string in 4-octet dotted
+     * notation.
+     *
+     * @return A string of the IPv4 host address.
+     */
     plString GetHostString() const;
+
+    /**
+     * Return the IPv4 address and port number of the host as a string in
+     * 4-octet dotted notation with a colon separated port.
+     *
+     * @return A string of the IPv4 host address and port number.
+     */
     plString GetHostWithPort() const;
+
+    /**
+     * Returns a string representation of the host address and port number.
+     *
+     * @return A string representation of the address.
+     */
     plString AsString() const;
 
+    /**
+     * Reads and deserializes the address from a stream.
+     *
+     * @param stream The stream from which to read the address.
+     */
     void Read(hsStream * stream);
+
+    /**
+     * Serializes and writes the address to a stream.
+     *
+     * @param stream The stream to which to write the address.
+     */
     void Write(hsStream * stream);
 };