Update and fix the docstrings

pipdeptree.py

@@ -11,7 +11,8 @@ flatten = chain.from_iterable
 def req_version(req):
     """Builds the version string for the requirement instance
 
-    :param req : representing requirement
+    :param req: requirement object
+    :returns: the version in desired format
     :rtype: string or NoneType
 
     """
@@ -21,9 +22,12 @@ def req_version(req):
 def top_pkg_name(pkg):
     """Builds the package name for top level package
 
-    The format is the same that's used by `pip freeze`
+    This just prints the name and the version of the package which may
+    not necessarily match with the output of `pip freeze` which also
+    includes info such as VCS source for editable packages
 
     :param pkg: pkg_resources.Distribution
+    :returns: the package name and version in the desired format
     :rtype: string
 
     """
@@ -39,6 +43,7 @@ def non_top_pkg_name(req, pkg):
 
     :param req: requirements instance
     :param pkg: pkg_resources.Distribution
+    :returns: the package name and version in the desired format
     :rtype: string
 
     """
@@ -55,10 +60,27 @@ def non_top_pkg_name(req, pkg):
 
 
 def top_pkg_src(pkg):
+    """Returns the frozen package name
+
+    The may or may not be the same as the package name.
+
+    :param pkg: pkg_resources.Distribution
+    :returns: frozen name of the package
+    :rtype: string
+
+    """
     return str(pip.FrozenRequirement.from_dist(pkg, [])).strip()
 
 
-def non_top_pkg_src(_, pkg):
+def non_top_pkg_src(_req, pkg):
+    """FIXME! briefly describe function
+
+    :param _req: the requirements instance
+    :param pkg: pkg_resources.Distribution
+    :returns: frozen name of the package
+    :rtype: string
+
+    """
     return top_pkg_src(pkg)