realm domains: improve doc text

It is quite unclear how realm domains behave without reading source
code. New doc text describes its purpose and how it is managed.

https://pagure.io/freeipa/issue/7424

Reviewed-By: Alexander Bokovoy <abokovoy@redhat.com>
Reviewed-By: Florence Blanc-Renaud <frenaud@redhat.com>

ipaserver/plugins/realmdomains.py

@@ -36,6 +36,16 @@ Realm domains
 
 Manage the list of domains associated with IPA realm.
 
+This list is useful for Domain Controllers from other realms which have
+established trust with this IPA realm. They need the information to know
+which request should be forwarded to KDC of this IPA realm.
+
+Automatic management: a domain is automatically added to the realm domains
+list when a new DNS Zone managed by IPA is created. Same applies for deletion.
+
+Externally managed DNS: domains which are not managed in IPA server DNS
+need to be manually added to the list using ipa realmdomains-mod command.
+
 EXAMPLES:
 
  Display the current list of realm domains:
@@ -118,10 +128,22 @@ class realmdomains(LDAPObject):
     )
 
 
-
 @register()
 class realmdomains_mod(LDAPUpdate):
-    __doc__ = _('Modify realm domains.')
+    __doc__ = _("""
+    Modify realm domains
+
+    DNS check: When manually adding a domain to the list, a DNS check is
+    performed by default. It ensures that the domain is associated with
+    the IPA realm, by checking whether the domain has a _kerberos TXT record
+    containing the IPA realm name. This check can be skipped by specifying
+    --force option.
+
+    Removal: when a realm domain which has a matching DNS zone managed by
+    IPA is being removed, a corresponding _kerberos TXT record in the zone is
+    removed automatically as well. Other records in the zone or the zone
+    itself are not affected.
+    """)
 
     takes_options = LDAPUpdate.takes_options + (
         Flag('force',