Improved the documentation of known_hosts

The documentation for the key parameter was lacking in specificity and
also lacking in testing. These parts are both remedied herein.

Fixes #43157

lib/ansible/modules/system/known_hosts.py

@@ -31,7 +31,11 @@ options:
   key:
     description:
       - The SSH public host key, as a string (required if state=present, optional when state=absent, in which case all keys for the host are removed).
-        The key must be in the right format for ssh (see sshd(8), section "SSH_KNOWN_HOSTS FILE FORMAT")
+        The key must be in the right format for ssh (see sshd(8), section "SSH_KNOWN_HOSTS FILE FORMAT").
+
+        Specifically, the key should not match the format that is found in an SSH pubkey file, but should rather have the hostname prepended to a
+        line that includes the pubkey, the same way that it would appear in the known_hosts file. The value prepended to the line must also match
+        the value of the name parameter.
   path:
     description:
       - The known_hosts file to edit

test/units/modules/system/test_known_hosts.py

@@ -1,10 +1,12 @@
 import os
 import tempfile
+import ansible.module_utils.basic as basic
 
 from ansible.compat.tests import unittest
 from ansible.module_utils._text import to_bytes
+from ansible.module_utils.basic import AnsibleModule
 
-from ansible.modules.system.known_hosts import compute_diff
+from ansible.modules.system.known_hosts import compute_diff, sanity_check
 
 
 class KnownHostsDiffTestCase(unittest.TestCase):
@@ -94,3 +96,12 @@ class KnownHostsDiffTestCase(unittest.TestCase):
             'before': 'two.example.com ssh-rsa BBBBetc\n',
             'after': 'two.example.com ssh-rsa BBBBetc\n',
         })
+
+    def test_sanity_check(self):
+        basic._load_params = lambda: {}
+        # Module used internally to execute ssh-keygen system executable
+        module = AnsibleModule(argument_spec={})
+        host = '10.0.0.1'
+        key = '%s ssh-rsa ASDF foo@bar' % (host,)
+        keygen = module.get_bin_path('ssh-keygen')
+        sanity_check(module, host, key, keygen)