commit 617640e0a358dc29c5e4f82eb6b828030ef21670
from: Alexander Barton <alex@barton.de>
date: Tue Aug 17 18:51:14 2010 UTC

Clean up an document Client_Hostname() and Client_Mask()

commit - f72e22d3611161af79a7c3240ff4700c0d70eb26
commit + 617640e0a358dc29c5e4f82eb6b828030ef21670
blob - 96d40d2923d89c932568c0750685e0fa3e25acdb
blob + a067ef72f6fda57488af438045cb8a0abc215e9f
--- src/ngircd/client.c
+++ src/ngircd/client.c
@@ -647,10 +647,15 @@ Client_OrigUser(CLIENT *Client) {
 #endif
 
 
-GLOBAL char *
-Client_Hostname( CLIENT *Client )
+/**
+ * Return the hostname of a client.
+ * @param Client Pointer to client structure
+ * @return Pointer to client hostname
+ */
+GLOBAL char *
+Client_Hostname(CLIENT *Client)
 {
-	assert( Client != NULL );
+	assert (Client != NULL);
 	return Client->host;
 } /* Client_Hostname */
 
@@ -727,20 +732,27 @@ Client_NextHop( CLIENT *Client )
 
 
 /**
- * return Client-ID ("client!user@host"), this ID is needed for e.g.
- * prefixes.  Returnes pointer to static buffer.
+ * Return ID of a client: "client!user@host"
+ * This client ID is used for IRC prefixes, for example.
+ * Please note that this function uses a global static buffer, so you can't
+ * nest invocations without overwriting erlier results!
+ * @param Client Pointer to client structure
+ * @return Pointer to global buffer containing the client ID
  */
 GLOBAL char *
 Client_Mask( CLIENT *Client )
 {
-	static char GetID_Buffer[GETID_LEN];
+	static char Mask_Buffer[GETID_LEN];
 
-	assert( Client != NULL );
+	assert (Client != NULL);
 
-	if( Client->type == CLIENT_SERVER ) return Client->id;
+	/* Servers: return name only, there is no "mask" */
+	if (Client->type == CLIENT_SERVER)
+		return Client->id;
 
-	snprintf(GetID_Buffer, GETID_LEN, "%s!%s@%s", Client->id, Client->user, Client->host);
-	return GetID_Buffer;
+	snprintf(Mask_Buffer, GETID_LEN, "%s!%s@%s",
+		 Client->id, Client->user, Client->host);
+	return Mask_Buffer;
 } /* Client_Mask */