lib.sources: Improve docs

Change comment type so than nixdoc picks them up into Nixpkgs manual.
Also improve phrasing a bit and move stuff around so that it is formatted better.

lib/sources.nix

@@ -20,17 +20,26 @@ let
     readFile
     ;
 
-  # Returns the type of a path: regular (for file), symlink, or directory
-  pathType = p: getAttr (baseNameOf p) (readDir (dirOf p));
+  /*
+    Returns the type of a path: regular (for file), symlink, or directory.
+  */
+  pathType = path: getAttr (baseNameOf path) (readDir (dirOf path));
 
-  # Returns true if the path exists and is a directory, false otherwise
-  pathIsDirectory = p: if pathExists p then (pathType p) == "directory" else false;
+  /*
+    Returns true if the path exists and is a directory, false otherwise.
+  */
+  pathIsDirectory = path: if pathExists path then (pathType path) == "directory" else false;
 
-  # Returns true if the path exists and is a regular file, false otherwise
-  pathIsRegularFile = p: if pathExists p then (pathType p) == "regular" else false;
+  /*
+    Returns true if the path exists and is a regular file, false otherwise.
+  */
+  pathIsRegularFile = path: if pathExists path then (pathType path) == "regular" else false;
 
-  # Bring in a path as a source, filtering out all Subversion and CVS
-  # directories, as well as backup files (*~).
+  /*
+    A basic filter for `cleanSourceWith` that removes
+    directories of version control system, backup files (*~)
+    and some generated files.
+  */
   cleanSourceFilter = name: type: let baseName = baseNameOf (toString name); in ! (
     # Filter out version control software files/directories
     (baseName == ".git" || type == "directory" && (baseName == ".svn" || baseName == "CVS" || baseName == ".hg")) ||
@@ -48,43 +57,48 @@ let
     (type == "unknown")
   );
 
-  # Filters a source tree removing version control files and directories using cleanSourceWith
-  #
-  # Example:
-  #          cleanSource ./.
+  /*
+    Filters a source tree removing version control files and directories using cleanSourceFilter.
+
+    Example:
+             cleanSource ./.
+  */
   cleanSource = src: cleanSourceWith { filter = cleanSourceFilter; inherit src; };
 
-  # Like `builtins.filterSource`, except it will compose with itself,
-  # allowing you to chain multiple calls together without any
-  # intermediate copies being put in the nix store.
-  #
-  #     lib.cleanSourceWith {
-  #       filter = f;
-  #       src = lib.cleanSourceWith {
-  #         filter = g;
-  #         src = ./.;
-  #       };
-  #     }
-  #     # Succeeds!
-  #
-  #     builtins.filterSource f (builtins.filterSource g ./.)
-  #     # Fails!
-  #
-  # Parameters:
-  #
-  #   src:      A path or cleanSourceWith result to filter and/or rename.
-  #
-  #   filter:   A function (path -> type -> bool)
-  #             Optional with default value: constant true (include everything)
-  #             The function will be combined with the && operator such
-  #             that src.filter is called lazily.
-  #             For implementing a filter, see
-  #             https://nixos.org/nix/manual/#builtin-filterSource
-  #
-  #   name:     Optional name to use as part of the store path.
-  #             This defaults to `src.name` or otherwise `"source"`.
-  #
-  cleanSourceWith = { filter ? _path: _type: true, src, name ? null }:
+  /*
+    Like `builtins.filterSource`, except it will compose with itself,
+    allowing you to chain multiple calls together without any
+    intermediate copies being put in the nix store.
+
+    Example:
+        lib.cleanSourceWith {
+          filter = f;
+          src = lib.cleanSourceWith {
+            filter = g;
+            src = ./.;
+          };
+        }
+        # Succeeds!
+
+        builtins.filterSource f (builtins.filterSource g ./.)
+        # Fails!
+
+  */
+  cleanSourceWith =
+    {
+      # A path or cleanSourceWith result to filter and/or rename.
+      src,
+      # Optional with default value: constant true (include everything)
+      # The function will be combined with the && operator such
+      # that src.filter is called lazily.
+      # For implementing a filter, see
+      # https://nixos.org/nix/manual/#builtin-filterSource
+      # Type: A function (path -> type -> bool)
+      filter ? _path: _type: true,
+      # Optional name to use as part of the store path.
+      # This defaults to `src.name` or otherwise `"source"`.
+      name ? null
+    }:
     let
       orig = toSourceAttributes src;
     in fromSourceAttributes {
@@ -116,9 +130,11 @@ let
         satisfiesSubpathInvariant = src ? satisfiesSubpathInvariant && src.satisfiesSubpathInvariant;
       };
 
-  # Filter sources by a list of regular expressions.
-  #
-  # E.g. `src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]`
+  /*
+    Filter sources by a list of regular expressions.
+
+    Example: src = sourceByRegex ./my-subproject [".*\.py$" "^database.sql$"]
+  */
   sourceByRegex = src: regexes:
     let
       isFiltered = src ? _isLibCleanSourceWith;
@@ -153,8 +169,11 @@ let
 
   pathIsGitRepo = path: (tryEval (commitIdFromGitRepo path)).success;
 
-  # Get the commit id of a git repo
-  # Example: commitIdFromGitRepo <nixpkgs/.git>
+  /*
+    Get the commit id of a git repo.
+
+    Example: commitIdFromGitRepo <nixpkgs/.git>
+  */
   commitIdFromGitRepo =
     let readCommitFromFile = file: path:
         let fileName       = toString path + "/" + file;