From 952a82cca08c8066de0880f973080e93c7e49a96 Mon Sep 17 00:00:00 2001
From: Jan-Piet Mens <jpmens@gmail.com>
Date: Mon, 17 Sep 2012 15:11:04 +0200
Subject: [PATCH] First attempt at standardizing DOCUMENTATION string (new
 DICT)

---
 get_url | 41 +++++++++++++++++++++++++++++++++++++++++
 raw     | 20 ++++++++++++++++++++
 setup   | 23 +++++++++++++++++++++++
 3 files changed, 84 insertions(+)

diff --git a/get_url b/get_url
index 37a713d3226..15e8caa4389 100755
--- a/get_url
+++ b/get_url
@@ -24,6 +24,47 @@ import shutil
 import datetime
 import tempfile
 
+DOCUMENTATION = '''
+---
+module: get_url
+short_description: Downloads files from HTTP, HTTPS, or FTP to node
+description: >
+     Downloads files from HTTP, HTTPS, or FTP to the remote server. The remote
+     server must have direct access to the remote resource.
+version_added: "0.6"
+options:
+  - url:
+      description: HTTP, HTTPS, or FTP URL
+      required: true
+      default: null
+      aliases: []
+  - dest:
+      description: absolute path of where to download the file to. If dest is a
+            directory, the basename of the file on the remote server will be used. If
+            a directory, thirsty=yes must also be set.
+      required: true
+      default: null
+  - thirsty:
+      description: if yes, will download the file every time and replace the
+           file if the contents change. if no, the file will only be downloaded if
+           the destination does not exist. Generally should be 'yes' only for small
+           local files. prior to 0.6, acts if 'yes' by default.
+      version_added: "0.7"
+      required: false
+      choices: [ "yes", "no" ]
+      default: "no"
+  - others:
+       description: all arguments accepted by the file module also work here
+       required: false
+examples:
+   - code: get_url url=http://example.com/path/file.conf dest=/etc/foo.conf mode=0440
+     description: Obtain and install config file
+notes: >
+    This module doesn't support proxies or passwords.
+# informational: requirements for nodes
+requirements: [ urllib2, urlparse ]
+'''
+
 HAS_URLLIB2=True
 try:
     import urllib2
diff --git a/raw b/raw
index 9132aeebbed..af9ec64ac32 100755
--- a/raw
+++ b/raw
@@ -1 +1,21 @@
 # this is a virtual module that is entirely implemented server side
+
+DOCUMENTATION = '''
+---
+module: raw
+short_description: Executes a low-down and dirty SSH command, not going through the module subsystem.
+description: >
+     Executes a low-down and dirty SSH command, not going through the module
+     subsystem. This is useful and should only be done in two cases. The first
+     case is installing python-simplejson on older (python 2.4 and before)
+     hosts that need it as a dependency to run modules, since nearly all core
+     modules require it. Another is speaking to any devices such as routers
+     that do not have any Python installed. In any other case, using the
+     'shell' or 'command' module is much more appropriate. Arguments given to
+     'raw' are run directly through the configured remote shell and only output
+     is returned. There is no error detection or change handler support for
+     this module
+examples:
+    - code: ansible newhost.example.com -m raw -a "yum -y install python-simplejson"
+      description: Example from /usr/bin/ansible to bootstrap a legacy python 2.4 host
+'''
diff --git a/setup b/setup
index 5499c2f8576..b448961e4c1 100755
--- a/setup
+++ b/setup
@@ -26,6 +26,29 @@ import re
 import socket
 import struct
 
+DOCUMENTATION = '''
+---
+module: setup
+short_description: Gathers facts about remote hosts
+description: >
+     This module is automatically called by playbooks to gather useful
+     variables about remote hosts that can be used in playbooks. It can also be
+     executed directly by /usr/bin/ansible to check what variables are
+     available to a host. Ansible provides many 'facts' about the system,
+     automatically.
+notes: >
+    More ansible facts will be added with successive releases. If facter or
+    ohai are installed, variables from these programs will also be snapshotted
+    into the JSON file for usage in templating. These variables are prefixed
+    with facter_ and ohai_ so it's easy to tell their source. All variables are
+    bubbled up to the caller. Using the ansible facts and choosing to not
+    install facter and ohai means you can avoid ruby-dependencies on your
+    remote systems.
+examples:
+    - code: ansible all -m setup -tree /tmp/facts
+      description: Obtain facts from all hosts and store them indexed by hostname at /tmp/facts.
+'''
+
 try:
     import selinux
     HAVE_SELINUX=True