Merge pull request #1054 from jpmens/geturl_doc1

First attempt at standardizing DOCUMENTATION string

library/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

library/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
+'''

library/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