complete plugin docs (#42355)

* complete plugin docs

  * add missing 'plugin' option
  * user and password are now 'correctly' required
  * added  inventory source example and extension information for user

lib/ansible/plugins/inventory/foreman.py

@@ -12,16 +12,23 @@ DOCUMENTATION = '''
     version_added: "2.6"
     description:
         - Get inventory hosts from the foreman service.
+        - "Uses a configuration file as an inventory source, it must end in foreman.yml or foreman.yaml and has a ``plugin: foreman`` entry."
     extends_documentation_fragment:
         - inventory_cache
     options:
+      plugin:
+        description: the name of this plugin, it should alwys be set to 'foreman' for this plugin to recognize it as it's own.
+        required: True
+        choices: ['foreman']
       url:
         description: url to foreman
         default: 'http://localhost:300'
       user:
         description: foreman authentication user
+        required: True
       password:
         description: forman authentication password
+        required: True
       validate_certs:
         description: verify SSL certificate if using https
         type: boolean
@@ -42,6 +49,15 @@ DOCUMENTATION = '''
         default: False
 '''
 
+EXAMPLES = '''
+# my.foreman.yml
+plugin: foreman
+url: http://localhost:2222
+user: ansible-tester
+password: secure
+validate_certs: False
+'''
+
 import re
 
 from collections import MutableMapping