fixes to config/setting retrieval

- better variable precedence management
- universal plugin option handling
- also updated comments for future directions
- leverage fragments for plugins
- removed fact namespacing
- added 'firendly name' field
- updated missing descriptions
- removed some unused yaml entries, updated others to reflect possible future
- documented more plugins
- allow reading docs using alias
- short licenses
- corrected args for 'all plugins'
- fixed -a option for ansible-doc
- updated vars plugins to allow docs
- fixed 'gathering'
- only set options IF connection
- added path list and renamed pathspec mostly the diff is , vs : as separator
- readded removed config entries that were deprecated but had no message ... and deprecated again
- now deprecated entries give warning when set

lib/ansible/plugins/callback/mail.py

@@ -1,8 +1,28 @@
 # -*- coding: utf-8 -*-
-
 # Copyright: (c) 2012, Dag Wieers <dag@wieers.com>
 # GNU General Public License v3.0+ (see COPYING or https://www.gnu.org/licenses/gpl-3.0.txt)
 
+'''
+DOCUMENTATION:
+    callback: mail
+    type: notification
+    short_description: Sends failure events via email
+    description:
+      - This callback will report failures via email
+    version_added: "2.3"
+    requirements:
+      - whitelisting in configuration
+      - logstash (python library)
+    options:
+      mta:
+        description: Mail Transfer Agent, server that accepts SMTP
+        env:
+          - name: SMTPHOST
+        default: localhost
+    note:
+      - "TODO: expand configuration options now that plugins can leverage Ansible's configuration"
+'''
+
 from __future__ import (absolute_import, division, print_function)
 __metaclass__ = type