Improve docs for public-address configuration [CTT-866]

docs/modules/clients/pages/java.adoc

@@ -1917,9 +1917,14 @@ See xref:extending-hazelcast:discovery-spi.adoc[Discovery SPI] for more informat
 |Enables the discovery joiner to use public IPs from `DiscoveredNode`.
 See xref:extending-hazelcast:discovery-spi.adoc[Discovery SPI] for more information.
 When set to `true`, the client assumes that it needs to use public IP addresses reported by the members.
-When set to `false`, the client always uses private addresses reported by the members. If it is `null`,
-the client will try to infer how the discovery mechanism should be based on the reachability of the members.
-This inference is not 100% reliable and may result in false-negatives.
+When set to `false`, the client always uses private addresses reported by the members.
+If not set, the client attempts to infer which address type to use by testing member reachability.
+The inference checks only a small sample of members (3 by default) with fixed timeouts, so it is
+not 100% reliable and may produce incorrect results in environments with variable network latency
+or partial connectivity. Additionally, inference is skipped when SSL/TLS is enabled, defaulting to
+private addresses.
+When members are configured with xref:clusters:network-configuration.adoc#public-address[public addresses],
+we recommend explicitly setting this property to `true` rather than relying on inference.
 
 |`hazelcast.client.event.queue.capacity`
 |1000000

docs/modules/clusters/pages/network-configuration.adoc

@@ -10,13 +10,26 @@ available configurations that you can perform under the `network` element.
 == Public Address
 
 `public-address` overrides the public address of a member. By default, a member
-selects its socket address as its public address. But behind a network address translation (NAT),
-two endpoints (members) may not be able to see/access each other.
-If both members set their public addresses to their defined addresses on NAT,
-then that way they can communicate with each other. In this case, their public addresses
-are not an address of a local network interface but a virtual address defined by NAT.
-It is optional to set and useful when you have a private cloud.
-Note that, the value for this element should be given in the format *`host IP address:port number`*.
+selects its socket address as its public address.
+
+While commonly used for network address translation (NAT) scenarios, `public-address`
+can be set to any reachable address or hostname that clients should use to connect to the member.
+Common use cases include:
+
+* **NAT environments**: When members are behind NAT, set the public address to the
+  externally visible address so that other members and clients can reach them.
+* **Hostname-based addressing**: Set a DNS hostname instead of an IP address for
+  easier management in environments where IP addresses may change.
+* **Split-horizon DNS**: When internal and external clients need to use different
+  addresses to reach the same member.
+* **Private cloud deployments**: When the member's socket address is not directly
+  accessible from outside the private network.
+
+The value can be specified as either:
+
+* An IP address with port: `11.22.33.44:5555`
+* A hostname with port: `member1.example.com:5555`
+
 See the following examples.
 
 [tabs] 
@@ -55,6 +68,62 @@ config.getNetworkConfig()
 ----
 ====
 
+=== How Public Address Affects Hazelcast Features
+
+The `public-address` setting is primarily used for client connections. It does not change
+how members communicate with each other internally. Understanding this distinction is
+important when configuring your cluster:
+
+[cols="1,3"]
+|===
+|Feature |Behavior with Public Address
+
+|**Member-to-member communication**
+|Always uses the primary member address (bind address), not the public address.
+Members within the cluster communicate directly using their internal addresses.
+
+|**Client connections**
+|Clients can use the public address to connect to members. This requires either
+explicitly enabling `hazelcast.discovery.public.ip.enabled` on the client, or
+relying on automatic inference (see <<client-public-address-discovery>>).
+
+|**CP Subsystem**
+|Uses the primary member address for CP member identity. Changing a member's
+address (for example, from IP to hostname) changes its identity in the CP subsystem,
+which can cause instability. See <<cp-address-changes>>.
+
+|**WAN Replication**
+|Uses standard member addressing. Configure target cluster endpoints explicitly
+in WAN replication configuration.
+|===
+
+[[client-public-address-discovery]]
+=== Client Public Address Discovery
+
+For clients to use members' public addresses, configure the
+`hazelcast.discovery.public.ip.enabled` property on the client:
+
+* `true`: The client always uses public addresses reported by members.
+* `false`: The client always uses private (internal) addresses reported by members.
+* Not set (default): The client attempts to infer which address type to use based on
+  reachability. See xref:clients:java.adoc#client-system-properties[Client System Properties]
+  for details on inference behavior and its limitations.
+
+NOTE: We recommend explicitly setting `hazelcast.discovery.public.ip.enabled` to `true`
+on clients when members are configured with public addresses, rather than relying on
+automatic inference.
+
+[[cp-address-changes]]
+=== Changing Member Addresses and CP Subsystem
+
+The CP Subsystem identifies members by their primary address. If you change a member's
+address configuration (for example, changing from an IP address to a hostname, or vice versa),
+the CP Subsystem treats this as a different member.
+
+WARNING: Changing the TCP-IP member configuration from an IP address to a hostname
+(or changing the hostname) while the CP Subsystem is in active use can cause CP group instability.
+To recover, you may need to delete the CP persistence directories and restart the
+CP Subsystem, which resets all CP data structures.
 
 [[port]]
 == Port