--- a/IPSocketAddress.st	Wed Jun 13 10:55:10 2018 +0200
+++ b/IPSocketAddress.st	Wed Jun 13 11:04:59 2018 +0200
@@ -68,8 +68,8 @@
 !IPSocketAddress class methodsFor:'instance creation'!
 
 addressString:aString
-    "convert an address given in a dot notation like 123.456.78.9.
-     handle IPv6SocketAddresses too."
+    "convert an address given in a dot notation like '123.456.78.9'.
+     Handles IPv6SocketAddresses too (if the string contains colons or brackets)."
 
     (self == IPSocketAddress and:[aString includesAny:'[:']) ifTrue:[
         ^ IPv6SocketAddress hostAddress:(IPv6SocketAddress hostAddressFromString:aString).
@@ -81,11 +81,13 @@
      IPSocketAddress addressString:'2001:4dd0:ffa3::1'
      IPSocketAddress addressString:'[2001:4dd0:ffa3::1]'
     "
+
+    "Modified (comment): / 13-06-2018 / 10:59:41 / Claus Gittinger"
 !
 
 allForHostName:name serviceName:portNrOrName type:socketTypeSymbol
-    "get a collection of new instance given a hostname, port or service and type.
-     Multi-homed hosts return more than one entry
+    "get a collection of new instances, given a hostname, port or service and type.
+     Multi-homed hosts return more than one entry.
      Redefined to cache the result of the name-lookup.
 
      Take care, this resolves to IPv4-addresses only!!
@@ -124,6 +126,7 @@
 
     "Modified: / 17-06-2009 / 15:21:00 / sr"
     "Modified (comment): / 21-02-2017 / 20:59:52 / stefan"
+    "Modified (comment): / 13-06-2018 / 11:00:04 / Claus Gittinger"
 !
 
 localHost
@@ -162,9 +165,11 @@
 !IPSocketAddress class methodsFor:'addressing'!
 
 anyAddress
-    "return the anonymous addresses bytes"
+    "return the anonymous address's bytes"
 
     ^ #[0 0 0 0]
+
+    "Modified (comment): / 13-06-2018 / 11:00:59 / Claus Gittinger"
 !
 
 anyPort
@@ -208,6 +213,8 @@
 !IPSocketAddress class methodsFor:'caching'!
 
 addressCacheAt:aHostName
+    "retrieve a cached address for aHostName or nil, if not in the cache"
+
     |addrAndTime addressList time|
 
     addrCache notNil ifTrue:[
@@ -223,9 +230,12 @@
     ^ nil
 
     "Modified: / 26-04-2007 / 11:21:37 / cg"
+    "Modified (comment): / 13-06-2018 / 11:03:31 / Claus Gittinger"
 !
 
 addressCacheAt:aName put:anAddressList
+    "put a aHostName -> list-of-addresses into the cache"
+
     (addrCache isNil or:[addrCache size > self addressCacheSize]) ifTrue:[
         addrCache := Dictionary new.
     ].
@@ -233,30 +243,47 @@
     addrCache at:aName put:(anAddressList -> Timestamp now).
 
     "Modified: / 26-04-2007 / 11:23:26 / cg"
+    "Modified (comment): / 13-06-2018 / 11:04:00 / Claus Gittinger"
 !
 
 addressCacheSize
+    "get the number of cached name entries.
+     If never set explicitly, the default is 50 names"
+
     ^ AddressCacheSize ? 50
 
     "Created: / 26-04-2007 / 11:22:40 / cg"
+    "Modified (comment): / 13-06-2018 / 11:02:49 / Claus Gittinger"
 !
 
 addressCacheSize:aNumber
+    "set the number of cached name entries.
+     If never set explicitly, the default is 50 names"
+
     AddressCacheSize := aNumber
 
     "Created: / 26-04-2007 / 11:24:05 / cg"
+    "Modified (comment): / 13-06-2018 / 11:02:57 / Claus Gittinger"
 !
 
 cacheInvalidationTimeInterval
+    "return the cache invalidation interval.
+     If never set explicitly, the default is 30 seconds"
+     
     ^ CacheInvalidationTimeInterval ? 30
 
     "Created: / 26-04-2007 / 11:21:31 / cg"
+    "Modified (comment): / 13-06-2018 / 11:01:55 / Claus Gittinger"
 !
 
 cacheInvalidationTimeInterval:seconds
+    "set the cache invalidation interval.
+     If never set explicitly, the default is 30 seconds"
+     
     CacheInvalidationTimeInterval := seconds
 
     "Created: / 26-04-2007 / 11:29:28 / cg"
+    "Modified (comment): / 13-06-2018 / 11:02:07 / Claus Gittinger"
 !
 
 flushAddressCache