From 50cd366124510881147fc436aa3dc69f550f509c Mon Sep 17 00:00:00 2001
From: Lucas Meneghel Rodrigues <lmr@redhat.com>
Date: Tue, 22 Jul 2014 11:33:38 -0300
Subject: [PATCH] avocado.utils.misc: Improve function docstrings

Also, reorder write_file and write_one_line.

Signed-off-by: Lucas Meneghel Rodrigues <lmr@redhat.com>
---
 avocado/utils/misc.py | 33 +++++++++++++++++++++++++--------
 1 file changed, 25 insertions(+), 8 deletions(-)

diff --git a/avocado/utils/misc.py b/avocado/utils/misc.py
index d67c0992..f0fde189 100644
--- a/avocado/utils/misc.py
+++ b/avocado/utils/misc.py
@@ -19,10 +19,15 @@ log = logging.getLogger('avocado.test')
 
 def ask(question, auto=False):
     """
-    Raw input with a prompt.
+    Prompt the user with a (y/n) question.
 
     :param question: Question to be asked
+    :type question: str
     :param auto: Whether to return "y" instead of asking the question
+    :type auto: bool
+
+    :return: User answer
+    :rtype: str
     """
     if auto:
         log.info("%s (y/n) y" % question)
@@ -35,6 +40,10 @@ def read_file(filename):
     Read the entire contents of file.
 
     :param filename: Path to the file.
+    :type filename: str
+
+    :return: File contents
+    :rtype: str
     """
     with open(filename, 'r') as file_obj:
         contents = file_obj.read()
@@ -46,28 +55,36 @@ def read_one_line(filename):
     Read the first line of filename.
 
     :param filename: Path to the file.
+    :type filename: str
+
+    :return: First line contents
+    :rtype: str
     """
     with open(filename, 'r') as file_obj:
         line = file_obj.readline().rstrip('\n')
     return line
 
 
-def write_one_line(filename, line):
+def write_file(filename, data):
     """
-    Write one line of text to filename.
+    Write data to a file.
 
     :param filename: Path to the file.
+    :type filename: str
     :param line: Line to be written.
+    :type line: str
     """
-    write_file(filename, line.rstrip('\n') + '\n')
+    with open(filename, 'w') as file_obj:
+        file_obj.write(data)
 
 
-def write_file(filename, data):
+def write_one_line(filename, line):
     """
-    Write data to a file.
+    Write one line of text to filename.
 
     :param filename: Path to the file.
+    :type filename: str
     :param line: Line to be written.
+    :type line: str
     """
-    with open(filename, 'w') as file_obj:
-        file_obj.write(data)
+    write_file(filename, line.rstrip('\n') + '\n')
-- 
GitLab