Change touched -> touch for new file state, and cleaning up docs

library/files/file

@@ -50,12 +50,13 @@ options:
         exist, see the M(copy) or M(template) module if you want that behavior.
         If C(link), the symbolic link will be created or changed. Use C(hard)
         for hardlinks. If C(absent), directories will be recursively deleted,
-        and files or symlinks will be unlinked. If C(touched), existing file and
+        and files or symlinks will be unlinked. If C(touch), an empty file will 
-        directory will change file access and modification times, not existing 
+        be created if the c(dest) does not exist, while an existing file or
-        file will be created.
+        directory will receive updated file access and modification times (similar
+        to the way `touch` works from the command line).
     required: false
     default: file
-    choices: [ file, link, directory, hard, touched, absent ]
+    choices: [ file, link, directory, hard, touch, absent ]
   mode:
     required: false
     default: null
@@ -141,7 +142,7 @@ def main():
 
     module = AnsibleModule(
         argument_spec = dict(
-            state = dict(choices=['file','directory','link','hard','touched','absent'], default='file'),
+            state = dict(choices=['file','directory','link','hard','touch','absent'], default='file'),
             path  = dict(aliases=['dest', 'name'], required=True),
             recurse  = dict(default='no', type='bool'),
             force = dict(required=False,default=False,type='bool'),
@@ -225,7 +226,7 @@ def main():
         module.exit_json(path=path, changed=True)
 
     if prev_state != 'absent' and prev_state != state:
-        if not (force and prev_state == 'file' and state == 'link') and state != 'touched':
+        if not (force and prev_state == 'file' and state == 'link') and state != 'touch':
             module.fail_json(path=path, msg='refusing to convert between %s and %s for %s' % (prev_state, state, src))
 
     if prev_state == 'absent' and state == 'absent':
@@ -309,7 +310,7 @@ def main():
         changed = module.set_file_attributes_if_different(file_args, changed)
         module.exit_json(dest=path, src=src, changed=changed)
 
-    elif state == 'touched':
+    elif state == 'touch':
         if module.check_mode:
             module.exit_json(path=path, skipped=True)
 
@@ -324,7 +325,7 @@ def main():
             try:
                 open(path, 'w').close()
             except OSError, e:
-                module.fail_json(path=path, msg='Error while touching non-existing target: %s' % str(e))
+                module.fail_json(path=path, msg='Error, could not touch target: %s' % str(e))
         module.set_file_attributes_if_different(file_args, True)
         module.exit_json(dest=path, changed=True)