DOCS: standardize on EXAMPLES (a.k.a. Docs-JumboPatch JetLag Edition)

Migrated all examples: in DOCUMENTATION=''' string to standalone EXAMPLES=''' string
  Added deprecation warning to moduledev.rst and remove deprecated example from it
  Fixed up a few typos and uppercased some acronyms.
  add consistency to how EXAMPLES are formatted

library/database/mongodb_user

@@ -67,11 +67,6 @@ options:
         required: false
         default: present
         choices: [ "present", "absent" ]
-examples:
-    - code: "mongodb_user: database=burgers name=bob password=12345 state=present"
-      description: Create 'burgers' database user with name 'bob' and password '12345'.
-    - code: "mongodb_user: database=burgers name=bob state=absent"
-      description: Delete 'burgers' database user with name 'bob'.
 notes:
     - Requires the pymongo Python package on the remote host, version 2.4.2+. This
       can be installed using pip or the OS package manager. @see http://api.mongodb.org/python/current/installation.html
@@ -79,6 +74,14 @@ requirements: [ "pymongo" ]
 author: Elliott Foster
 '''
 
+EXAMPLES = '''
+# Create 'burgers' database user with name 'bob' and password '12345'.
+- mongodb_user: database=burgers name=bob password=12345 state=present
+
+# Delete 'burgers' database user with name 'bob'.
+- mongodb_user: database=burgers name=bob state=absent
+'''
+
 import ConfigParser
 try:
     from pymongo import MongoClient

library/database/mysql_db

@@ -72,9 +72,6 @@ options:
     description:
       - Where to dump/get the C(.sql) file
     required: false
-examples:
-   - code: "mysql_db: db=bobdata state=present"
-     description: Create a new database with name 'bobdata'
 notes:
    - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
      is as easy as apt-get install python-mysqldb. (See M(apt).)
@@ -86,6 +83,11 @@ requirements: [ ConfigParser ]
 author: Mark Theunissen
 '''
 
+EXAMPLES = '''
+# Create a new database with name 'bobdata'
+- mysql_db: db=bobdata state=present
+'''
+
 import ConfigParser
 import os
 try:

library/database/mysql_user

@@ -72,15 +72,6 @@ options:
     required: false
     default: present
     choices: [ "present", "absent" ]
-examples:
-   - code: "mysql_user: name=bob password=12345 priv=*.*:ALL state=present"
-     description: Create database user with name 'bob' and password '12345' with all database privileges
-   - code: "mysql_user: login_user=root login_password=123456 name=sally state=absent"
-     description: Ensure no user named 'sally' exists, also passing in the auth credentials.
-   - code: mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
-     description: Example privileges string format
-   - code: "mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock"
-     description: Example using login_unix_socket to connect to server
 notes:
    - Requires the MySQLdb Python package on the remote host. For Ubuntu, this
      is as easy as apt-get install python-mysqldb.
@@ -99,9 +90,22 @@ author: Mark Theunissen
 '''
 
 EXAMPLES = """
+# Create database user with name 'bob' and password '12345' with all database privileges
+- mysql_user: name=bob password=12345 priv=*.*:ALL state=present
+
+# Ensure no user named 'sally' exists, also passing in the auth credentials.
+- mysql_user: login_user=root login_password=123456 name=sally state=absent
+
+# Example privileges string format
+mydb.*:INSERT,UPDATE/anotherdb.*:SELECT/yetanotherdb.*:ALL
+
+# Example using login_unix_socket to connect to server
+- mysql_user: name=root password=abc123 login_unix_socket=/var/run/mysqld/mysqld.sock
+
 # Example .my.cnf file for setting the root password
 # Note: don't use quotes around the password, because the mysql_user module
 # will include them in the password but the mysql client will not
+
 [client]
 user=root
 password=n<_665{vS43y

library/database/postgresql_db

@@ -80,11 +80,6 @@ options:
     required: false
     default: present
     choices: [ "present", "absent" ]
-examples:
-   - code: "postgresql_db: db=acme"
-     description: Create a new database with name C(acme)
-   - code: "postgresql_db: db=acme encoding='UTF-8' lc_collate='de_DE.UTF-8' lc_ctype='de_DE.UTF-8' template='template0'"
-     description: Create a new database with name C(acme) and specific encoding and locale settings. If a template different from C(template0) is specified, encoding and locale settings must match those of the template.
 notes:
    - The default authentication assumes that you are either logging in as or sudo'ing to the C(postgres) account on the host.
    - This module uses I(psycopg2), a Python PostgreSQL database adapter. You must ensure that psycopg2 is installed on
@@ -93,6 +88,20 @@ requirements: [ psycopg2 ]
 author: Lorin Hochstein
 '''
 
+EXAMPLES = '''
+# Create a new database with name "acme"
+- postgresql_db: db=acme
+
+# Create a new database with name "acme" and specific encoding and locale
+# settings. If a template different from "template0" is specified, encoding
+# and locale settings must match those of the template.
+- postgresql_db: db=acme
+                 encoding='UTF-8'
+                 lc_collate='de_DE.UTF-8'
+                 lc_ctype='de_DE.UTF-8'
+                 template='template0'
+'''
+
 try:
     import psycopg2
     import psycopg2.extras

library/database/postgresql_user

@@ -90,17 +90,6 @@ options:
     required: false
     default: present
     choices: [ "present", "absent" ]
-examples:
-   - code: "postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL"
-     description: Create django user and grant access to database and products table
-   - code: "postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER"
-     description: Create rails user, grant privilege to create other databases and demote rails from super user status
-   - code: "postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no"
-     description: Remove test user privileges from acme
-   - code: "postgresql_user: db=test user=test priv=ALL state=absent"
-     description: Remove test user from test database and the cluster
-   - code: INSERT,UPDATE/table:SELECT/anothertable:ALL
-     description: Example privileges string format
 notes:
    - The default authentication assumes that you are either logging in as or
      sudo'ing to the postgres account on the host.
@@ -117,6 +106,23 @@ requirements: [ psycopg2 ]
 author: Lorin Hochstein
 '''
 
+EXAMPLES = '''
+# Create django user and grant access to database and products table
+- postgresql_user: db=acme user=django password=ceec4eif7ya priv=CONNECT/products:ALL
+
+# Create rails user, grant privilege to create other databases and demote rails from super user status
+- postgresql_user: user=rails password=secret role_attr_flags=CREATEDB,NOSUPERUSER
+
+# Remove test user privileges from acme
+- postgresql_user: db=acme user=test priv=ALL/products:ALL state=absent fail_on_user=no
+
+# Remove test user from test database and the cluster
+- postgresql_user: db=test user=test priv=ALL state=absent
+
+# Example privileges string format
+INSERT,UPDATE/table:SELECT/anothertable:ALL
+'''
+
 import re
 
 try:

library/database/riak

@@ -73,15 +73,18 @@ options:
     default: kv
     aliases: []
     choices: ['kv']
-examples:
-   - code: "riak: command=join target_node=riak@10.1.1.1"
-     description: "Join's a Riak node to another node"
-   - code: "riak: wait_for_handoffs=yes"
-     description: "Wait for handoffs to finish.  Use with async and poll."
-   - code: "riak: wait_for_service=kv"
-     description: "Wait for riak_kv service to startup"
 '''
 
+EXAMPLES = '''
+# Join's a Riak node to another node
+- riak: command=join target_node=riak@10.1.1.1
+
+# Wait for handoffs to finish.  Use with async and poll.
+- riak: wait_for_handoffs=yes
+
+# Wait for riak_kv service to startup
+- riak: wait_for_service=kv
+'''
 
 
 import re