diff --git a/lib/ansible/plugins/inventory/foreman.py b/lib/ansible/plugins/inventory/foreman.py
index a8f23fd5e81..fd17eccf065 100644
--- a/lib/ansible/plugins/inventory/foreman.py
+++ b/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