known_hosts: update documentation (#70342)

* Update documentation as per sanity tests
* Added example about custom SSH port in example section

Fixes: #29236

Signed-off-by: Abhijeet Kasurde <akasurde@redhat.com>

lib/ansible/modules/known_hosts.py

@@ -7,7 +7,7 @@ from __future__ import absolute_import, division, print_function
 __metaclass__ = type
 
 
-DOCUMENTATION = '''
+DOCUMENTATION = r'''
 ---
 module: known_hosts
 short_description: Add or remove a host from the C(known_hosts) file
@@ -23,37 +23,43 @@ options:
     description:
       - The host to add or remove (must match a host specified in key). It will be converted to lowercase so that ssh-keygen can find it.
       - Must match with <hostname> or <ip> present in key attribute.
+      - For custom SSH port, C(name) needs to specify port as well. See example section.
     required: true
+    type: str
   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 SSH public host key, as a string.
-        The key must be in the right format for ssh (see sshd(8), section "SSH_KNOWN_HOSTS FILE FORMAT").
+      - Required if C(state=present), optional when C(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").
-        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
+      - 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.
-
+      - Should be of format `<hostname[,IP]> ssh-rsa <pubkey>`.
-        Should be of format `<hostname[,IP]> ssh-rsa <pubkey>`
+      - For custom SSH port, C(key) needs to specify port as well. See example section.
+    type: str
   path:
     description:
-      - The known_hosts file to edit
+      - The known_hosts file to edit.
-    default: "(homedir)+/.ssh/known_hosts"
+    default: "~/.ssh/known_hosts"
+    type: path
   hash_host:
     description:
-      - Hash the hostname in the known_hosts file
+      - Hash the hostname in the known_hosts file.
     type: bool
-    default: 'no'
+    default: "no"
     version_added: "2.3"
   state:
     description:
-      - I(present) to add the host key, I(absent) to remove it.
+      - I(present) to add the host key.
-    choices: [ "present", "absent" ]
+      - I(absent) to remove it.
-    default: present
+    choices: [ "absent", "present" ]
-requirements: [ ]
+    default: "present"
-author: "Matthew Vernon (@mcv21)"
+    type: str
+author:
+- Matthew Vernon (@mcv21)
 '''
 
-EXAMPLES = '''
+EXAMPLES = r'''
 - name: Tell the host about our servers it might want to ssh to
   known_hosts:
     path: /etc/ssh/ssh_known_hosts
@@ -66,6 +72,13 @@ EXAMPLES = '''
     key: host1.example.com,10.9.8.77 ssh-rsa ASDeararAIUHI324324  # some key gibberish
     path: /etc/ssh/ssh_known_hosts
     state: present
+
+- name: Add host with custom SSH port
+  known_hosts:
+    name: '[host1.example.com]:2222'
+    key: '[host1.example.com]:2222 ssh-rsa ASDeararAIUHI324324' # some key gibberish
+    path: /etc/ssh/ssh_known_hosts
+    state: present
 '''
 
 # Makes sure public host keys are present or absent in the given known_hosts

test/sanity/ignore.txt

@@ -151,9 +151,6 @@ lib/ansible/modules/hostname.py validate-modules:invalid-ansiblemodule-schema
 lib/ansible/modules/hostname.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/iptables.py pylint:blacklisted-name
 lib/ansible/modules/iptables.py validate-modules:parameter-list-no-elements
-lib/ansible/modules/known_hosts.py validate-modules:doc-default-does-not-match-spec
-lib/ansible/modules/known_hosts.py validate-modules:doc-missing-type
-lib/ansible/modules/known_hosts.py validate-modules:parameter-type-not-in-doc
 lib/ansible/modules/service.py validate-modules:nonexistent-parameter-documented
 lib/ansible/modules/service.py validate-modules:use-run-command-not-popen
 lib/ansible/modules/setup.py validate-modules:doc-missing-type