Improved API documentation (copied from SFML)

include/SFML/Network/IpAddress.h

@@ -32,7 +32,8 @@
 
 
 ////////////////////////////////////////////////////////////
-/// sfIpAddress provides easy manipulation of IP v4 addresses
+/// \brief Encapsulate an IPv4 network address
+///
 ////////////////////////////////////////////////////////////
 typedef struct
 {
@@ -41,22 +42,30 @@ typedef struct
 
 
 ////////////////////////////////////////////////////////////
-/// Construct an address from a string
+/// \brief Create an address from a string
 ///
-/// \param string : IP address ("xxx.xxx.xxx.xxx") or network name
+/// Here \a address can be either a decimal address
+/// (ex: "192.168.1.56") or a network name (ex: "localhost").
+///
+/// \param address IP address or network name
 ///
 /// \return Resulting address
 ///
 ////////////////////////////////////////////////////////////
-CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
+CSFML_API sfIpAddress sfIpAddress_FromString(const char* address);
 
 ////////////////////////////////////////////////////////////
-/// Construct an address from 4 bytes
+/// \brief Create an address from 4 bytes
 ///
-/// \param byte0 : First byte of the address
-/// \param byte1 : Second byte of the address
-/// \param byte2 : Third byte of the address
-/// \param byte3 : Fourth byte of the address
+/// Calling sfIpAddress_FromBytes(a, b, c, d) is equivalent
+/// to calling sfIpAddress_FromString("a.b.c.d"), but safer
+/// as it doesn't have to parse a string to get the address
+/// components.
+///
+/// \param byte0 First byte of the address
+/// \param byte1 Second byte of the address
+/// \param byte2 Third byte of the address
+/// \param byte3 Fourth byte of the address
 ///
 /// \return Resulting address
 ///
@@ -64,55 +73,88 @@ CSFML_API sfIpAddress sfIpAddress_FromString(const char* string);
 CSFML_API sfIpAddress sfIpAddress_FromBytes(sfUint8 byte0, sfUint8 byte1, sfUint8 byte2, sfUint8 byte3);
 
 ////////////////////////////////////////////////////////////
-/// Construct the address from a 32-bits integer
+/// \brief Construct an address from a 32-bits integer
 ///
-/// \param address : 4 bytes of the address packed into a 32-bits integer
+/// This function uses the internal representation of
+/// the address directly. It should be used for optimization
+/// purposes, and only if you got that representation from
+/// sfIpAddress_ToInteger.
+///
+/// \param address 4 bytes of the address packed into a 32-bits integer
+///
+/// \return Resulting address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_FromInteger(sfUint32 address);
 
 ////////////////////////////////////////////////////////////
-/// Get a string representation of an address
+/// \brief Get a string representation of an address
 ///
-/// \param address : Address to convert
-/// \param string :  Char array to fill (size must be >= 16)
+/// The returned string is the decimal representation of the
+/// IP address (like "192.168.1.56"), even if it was constructed
+/// from a host name.
+///
+/// \param address Address object
+///
+/// \return String representation of the address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API void sfIpAddress_ToString(sfIpAddress address, char* string);
 
 ////////////////////////////////////////////////////////////
-/// Get an integer representation of the address
+/// \brief Get an integer representation of the address
 ///
-/// \param address : Address to convert
+/// The returned number is the internal representation of the
+/// address, and should be used for optimization purposes only
+/// (like sending the address through a socket).
+/// The integer produced by this function can then be converted
+/// back to a sfIpAddress with sfIpAddress_FromInteger.
 ///
-/// \return 32-bits integer containing the 4 bytes of the address, in system endianness
+/// \param address Address object
+///
+/// \return 32-bits unsigned integer representation of the address
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfUint32 sfIpAddress_ToInteger(sfIpAddress address);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's local IP address (from the LAN point of view)
+/// \brief Get the computer's local address
 ///
-/// \return Local IP address
+/// The local address is the address of the computer from the
+/// LAN point of view, i.e. something like 192.168.1.56. It is
+/// meaningful only for communications over the local network.
+/// Unlike sfIpAddress_GetPublicAddress, this function is fast
+/// and may be used safely anywhere.
+///
+/// \return Local IP address of the computer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_GetLocalAddress(void);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's public IP address (from the web point of view).
+/// \brief Get the computer's public address
+///
+/// The public address is the address of the computer from the
+/// internet point of view, i.e. something like 89.54.1.169.
+/// It is necessary for communications over the world wide web.
 /// The only way to get a public address is to ask it to a
-/// distant website ; as a consequence, this function may be
-/// very slow -- use it as few as possible !
+/// distant website; as a consequence, this function depends on
+/// both your network connection and the server, and may be
+/// very slow. You should use it as few as possible. Because
+/// this function depends on the network connection and on a distant
+/// server, you may use a time limit if you don't want your program
+/// to be possibly stuck waiting in case there is a problem; use
+/// 0 to deactivate this limit.
 ///
-/// \param timeout : Maximum time to wait, in milliseconds (use 0 for no timeout)
+/// \param timeout Maximum time to wait, in milliseconds
 ///
-/// \return Public IP address
+/// \return Public IP address of the computer
 ///
 ////////////////////////////////////////////////////////////
 CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
 
 ////////////////////////////////////////////////////////////
-/// Get the computer's loopback address
+/// \brief Get the computer's loopback address
 ///
 /// \return Local host IP address (127.0.0.1, or "localhost")
 ///
@@ -120,7 +162,7 @@ CSFML_API sfIpAddress sfIpAddress_GetPublicAddress(sfUint32 timeout);
 CSFML_API sfIpAddress sfIpAddress_LocalHost(void);
 
 ////////////////////////////////////////////////////////////
-/// Get the empty/invalid address
+/// \brief Get the empty/invalid address
 ///
 /// \return Empty object that represents invalid addresses
 ///