Merge pull request #49383 from tazjin/docs/lib-docstrings

Update library function "docstrings" for nixdoc generation

1 files changed, 153 insertions, 51 deletions

diff --git a/lib/strings.nix b/lib/strings.nix
index 99399459bb48..4d7fa1e774d5 100644
--- a/lib/strings.nix
+++ b/lib/strings.nix
@@ -12,6 +12,8 @@ rec {
 
   /* Concatenate a list of strings.
 
+    Type: concatStrings :: [string] -> string
+
      Example:
        concatStrings ["foo" "bar"]
        => "foobar"
@@ -20,15 +22,19 @@ rec {
 
   /* Map a function over a list and concatenate the resulting strings.
 
+    Type: concatMapStrings :: (a -> string) -> [a] -> string
+
      Example:
        concatMapStrings (x: "a" + x) ["foo" "bar"]
        => "afooabar"
   */
   concatMapStrings = f: list: concatStrings (map f list);
 
-  /* Like `concatMapStrings' except that the f functions also gets the
+  /* Like `concatMapStrings` except that the f functions also gets the
      position as a parameter.
 
+     Type: concatImapStrings :: (int -> a -> string) -> [a] -> string
+
      Example:
        concatImapStrings (pos: x: "${toString pos}-${x}") ["foo" "bar"]
        => "1-foo2-bar"
@@ -37,17 +43,25 @@ rec {
 
   /* Place an element between each element of a list
 
+     Type: intersperse :: a -> [a] -> [a]
+
      Example:
        intersperse "/" ["usr" "local" "bin"]
        => ["usr" "/" "local" "/" "bin"].
   */
-  intersperse = separator: list:
+  intersperse =
+    # Separator to add between elements
+    separator:
+    # Input list
+    list:
     if list == [] || length list == 1
     then list
     else tail (lib.concatMap (x: [separator x]) list);
 
   /* Concatenate a list of strings with a separator between each element
 
+     Type: concatStringsSep :: string -> [string] -> string
+
      Example:
         concatStringsSep "/" ["usr" "local" "bin"]
         => "usr/local/bin"
@@ -55,43 +69,77 @@ rec {
   concatStringsSep = builtins.concatStringsSep or (separator: list:
     concatStrings (intersperse separator list));
 
-  /* First maps over the list and then concatenates it.
+  /* Maps a function over a list of strings and then concatenates the
+     result with the specified separator interspersed between
+     elements.
+
+     Type: concatMapStringsSep :: string -> (string -> string) -> [string] -> string
 
      Example:
         concatMapStringsSep "-" (x: toUpper x)  ["foo" "bar" "baz"]
         => "FOO-BAR-BAZ"
   */
-  concatMapStringsSep = sep: f: list: concatStringsSep sep (map f list);
+  concatMapStringsSep =
+    # Separator to add between elements
+    sep:
+    # Function to map over the list
+    f:
+    # List of input strings
+    list: concatStringsSep sep (map f list);
 
-  /* First imaps over the list and then concatenates it.
+  /* Same as `concatMapStringsSep`, but the mapping function
+     additionally receives the position of its argument.
 
-     Example:
+     Type: concatMapStringsSep :: string -> (int -> string -> string) -> [string] -> string
 
+     Example:
        concatImapStringsSep "-" (pos: x: toString (x / pos)) [ 6 6 6 ]
        => "6-3-2"
   */
-  concatImapStringsSep = sep: f: list: concatStringsSep sep (lib.imap1 f list);
+  concatImapStringsSep =
+    # Separator to add between elements
+    sep:
+    # Function that receives elements and their positions
+    f:
+    # List of input strings
+    list: concatStringsSep sep (lib.imap1 f list);
 
-  /* Construct a Unix-style search path consisting of each `subDir"
-     directory of the given list of packages.
+  /* Construct a Unix-style, colon-separated search path consisting of
+     the given `subDir` appended to each of the given paths.
+
+     Type: makeSearchPath :: string -> [string] -> string
 
      Example:
        makeSearchPath "bin" ["/root" "/usr" "/usr/local"]
        => "/root/bin:/usr/bin:/usr/local/bin"
-       makeSearchPath "bin" ["/"]
-       => "//bin"
+       makeSearchPath "bin" [""]
+       => "/bin"
   */
-  makeSearchPath = subDir: packages:
-    concatStringsSep ":" (map (path: path + "/" + subDir) (builtins.filter (x: x != null) packages));
+  makeSearchPath =
+    # Directory name to append
+    subDir:
+    # List of base paths
+    paths:
+    concatStringsSep ":" (map (path: path + "/" + subDir) (builtins.filter (x: x != null) paths));
+
+  /* Construct a Unix-style search path by appending the given
+     `subDir` to the specified `output` of each of the packages. If no
+     output by the given name is found, fallback to `.out` and then to
+     the default.
 
-  /* Construct a Unix-style search path, using given package output.
-     If no output is found, fallback to `.out` and then to the default.
+     Type: string -> string -> [package] -> string
 
      Example:
        makeSearchPathOutput "dev" "bin" [ pkgs.openssl pkgs.zlib ]
        => "/nix/store/9rz8gxhzf8sw4kf2j2f1grr49w8zx5vj-openssl-1.0.1r-dev/bin:/nix/store/wwh7mhwh269sfjkm6k5665b5kgp7jrk2-zlib-1.2.8/bin"
   */
-  makeSearchPathOutput = output: subDir: pkgs: makeSearchPath subDir (map (lib.getOutput output) pkgs);
+  makeSearchPathOutput =
+    # Package output to use
+    output:
+    # Directory name to append
+    subDir:
+    # List of packages
+    pkgs: makeSearchPath subDir (map (lib.getOutput output) pkgs);
 
   /* Construct a library search path (such as RPATH) containing the
      libraries for a set of packages
@@ -117,13 +165,12 @@ rec {
 
   /* Construct a perl search path (such as $PERL5LIB)
 
-     FIXME(zimbatm): this should be moved in perl-specific code
-
      Example:
        pkgs = import <nixpkgs> { }
        makePerlPath [ pkgs.perlPackages.libnet ]
        => "/nix/store/n0m1fk9c960d8wlrs62sncnadygqqc6y-perl-Net-SMTP-1.25/lib/perl5/site_perl"
   */
+  # FIXME(zimbatm): this should be moved in perl-specific code
   makePerlPath = makeSearchPathOutput "lib" "lib/perl5/site_perl";
 
   /* Construct a perl search path recursively including all dependencies (such as $PERL5LIB)
@@ -138,34 +185,51 @@ rec {
   /* Depending on the boolean `cond', return either the given string
      or the empty string. Useful to concatenate against a bigger string.
 
+     Type: optionalString :: bool -> string -> string
+
      Example:
        optionalString true "some-string"
        => "some-string"
        optionalString false "some-string"
        => ""
   */
-  optionalString = cond: string: if cond then string else "";
+  optionalString =
+    # Condition
+    cond:
+    # String to return if condition is true
+    string: if cond then string else "";
 
   /* Determine whether a string has given prefix.
 
+     Type: hasPrefix :: string -> string -> bool
+
      Example:
        hasPrefix "foo" "foobar"
        => true
        hasPrefix "foo" "barfoo"
        => false
   */
-  hasPrefix = pref: str:
-    substring 0 (stringLength pref) str == pref;
+  hasPrefix =
+    # Prefix to check for
+    pref:
+    # Input string
+    str: substring 0 (stringLength pref) str == pref;
 
   /* Determine whether a string has given suffix.
 
+     Type: hasSuffix :: string -> string -> bool
+
      Example:
        hasSuffix "foo" "foobar"
        => false
        hasSuffix "foo" "barfoo"
        => true
   */
-  hasSuffix = suffix: content:
+  hasSuffix =
+    # Suffix to check for
+    suffix:
+    # Input string
+    content:
     let
       lenContent = stringLength content;
       lenSuffix = stringLength suffix;
@@ -180,6 +244,8 @@ rec {
      Also note that Nix treats strings as a list of bytes and thus doesn't
      handle unicode.
 
+     Type: stringtoCharacters :: string -> [string]
+
      Example:
        stringToCharacters ""
        => [ ]
@@ -194,18 +260,25 @@ rec {
   /* Manipulate a string character by character and replace them by
      strings before concatenating the results.
 
+     Type: stringAsChars :: (string -> string) -> string -> string
+
      Example:
        stringAsChars (x: if x == "a" then "i" else x) "nax"
        => "nix"
   */
-  stringAsChars = f: s:
-    concatStrings (
+  stringAsChars =
+    # Function to map over each individual character
+    f:
+    # Input string
+    s: concatStrings (
       map f (stringToCharacters s)
     );
 
-  /* Escape occurrence of the elements of ‘list’ in ‘string’ by
+  /* Escape occurrence of the elements of `list` in `string` by
      prefixing it with a backslash.
 
+     Type: escape :: [string] -> string -> string
+
      Example:
        escape ["(" ")"] "(foo)"
        => "\\(foo\\)"
@@ -214,6 +287,8 @@ rec {
 
   /* Quote string to be used safely within the Bourne shell.
 
+     Type: escapeShellArg :: string -> string
+
      Example:
        escapeShellArg "esc'ape\nme"
        => "'esc'\\''ape\nme'"
@@ -222,6 +297,8 @@ rec {
 
   /* Quote all arguments to be safely passed to the Bourne shell.
 
+     Type: escapeShellArgs :: [string] -> string
+
      Example:
        escapeShellArgs ["one" "two three" "four'five"]
        => "'one' 'two three' 'four'\\''five'"
@@ -230,13 +307,15 @@ rec {
 
   /* Turn a string into a Nix expression representing that string
 
+     Type: string -> string
+
      Example:
        escapeNixString "hello\${}\n"
        => "\"hello\\\${}\\n\""
   */
   escapeNixString = s: escape ["$"] (builtins.toJSON s);
 
-  /* Obsolete - use replaceStrings instead. */
+  # Obsolete - use replaceStrings instead.
   replaceChars = builtins.replaceStrings or (
     del: new: s:
     let
@@ -256,6 +335,8 @@ rec {
 
   /* Converts an ASCII string to lower-case.
 
+     Type: toLower :: string -> string
+
      Example:
        toLower "HOME"
        => "home"
@@ -264,6 +345,8 @@ rec {
 
   /* Converts an ASCII string to upper-case.
 
+     Type: toUpper :: string -> string
+
      Example:
        toUpper "home"
        => "HOME"
@@ -273,7 +356,7 @@ rec {
   /* Appends string context from another string.  This is an implementation
      detail of Nix.
 
-     Strings in Nix carry an invisible `context' which is a list of strings
+     Strings in Nix carry an invisible `context` which is a list of strings
      representing store paths.  If the string is later used in a derivation
      attribute, the derivation will properly populate the inputDrvs and
      inputSrcs.
@@ -319,8 +402,9 @@ rec {
     in
       recurse 0 0;
 
-  /* Return the suffix of the second argument if the first argument matches
-     its prefix.
+  /* Return a string without the specified prefix, if the prefix matches.
+
+     Type: string -> string -> string
 
      Example:
        removePrefix "foo." "foo.bar.baz"
@@ -328,18 +412,23 @@ rec {
        removePrefix "xxx" "foo.bar.baz"
        => "foo.bar.baz"
   */
-  removePrefix = pre: s:
+  removePrefix =
+    # Prefix to remove if it matches
+    prefix:
+    # Input string
+    str:
     let
-      preLen = stringLength pre;
-      sLen = stringLength s;
+      preLen = stringLength prefix;
+      sLen = stringLength str;
     in
-      if hasPrefix pre s then
-        substring preLen (sLen - preLen) s
+      if hasPrefix prefix str then
+        substring preLen (sLen - preLen) str
       else
-        s;
+        str;
+
+  /* Return a string without the specified suffix, if the suffix matches.
 
-  /* Return the prefix of the second argument if the first argument matches
-     its suffix.
+     Type: string -> string -> string
 
      Example:
        removeSuffix "front" "homefront"
@@ -347,17 +436,21 @@ rec {
        removeSuffix "xxx" "homefront"
        => "homefront"
   */
-  removeSuffix = suf: s:
+  removeSuffix =
+    # Suffix to remove if it matches
+    suffix:
+    # Input string
+    str:
     let
-      sufLen = stringLength suf;
-      sLen = stringLength s;
+      sufLen = stringLength suffix;
+      sLen = stringLength str;
     in
-      if sufLen <= sLen && suf == substring (sLen - sufLen) sufLen s then
-        substring 0 (sLen - sufLen) s
+      if sufLen <= sLen && suffix == substring (sLen - sufLen) sufLen str then
+        substring 0 (sLen - sufLen) str
       else
-        s;
+        str;
 
-  /* Return true iff string v1 denotes a version older than v2.
+  /* Return true if string v1 denotes a version older than v2.
 
      Example:
        versionOlder "1.1" "1.2"
@@ -367,7 +460,7 @@ rec {
   */
   versionOlder = v1: v2: builtins.compareVersions v2 v1 == 1;
 
-  /* Return true iff string v1 denotes a version equal to or newer than v2.
+  /* Return true if string v1 denotes a version equal to or newer than v2.
 
      Example:
        versionAtLeast "1.1" "1.0"
@@ -459,6 +552,11 @@ rec {
   /* Create a fixed width string with additional prefix to match
      required width.
 
+     This function will fail if the input string is longer than the
+     requested length.
+
+     Type: fixedWidthString :: int -> string -> string
+
      Example:
        fixedWidthString 5 "0" (toString 15)
        => "00015"
@@ -509,8 +607,9 @@ rec {
     else
       false;
 
-  /* Convert string to int
-     Obviously, it is a bit hacky to use fromJSON that way.
+  /* Parse a string string as an int.
+
+     Type: string -> int
 
      Example:
        toInt "1337"
@@ -520,17 +619,18 @@ rec {
        toInt "3.14"
        => error: floating point JSON numbers are not supported
   */
+  # Obviously, it is a bit hacky to use fromJSON this way.
   toInt = str:
     let may_be_int = builtins.fromJSON str; in
     if builtins.isInt may_be_int
     then may_be_int
     else throw "Could not convert ${str} to int.";
 
-  /* Read a list of paths from `file', relative to the `rootPath'. Lines
-     beginning with `#' are treated as comments and ignored. Whitespace
-     is significant.
+  /* Read a list of paths from `file`, relative to the `rootPath`.
+     Lines beginning with `#` are treated as comments and ignored.
+     Whitespace is significant.
 
-     NOTE: this function is not performant and should be avoided
+     NOTE: This function is not performant and should be avoided.
 
      Example:
        readPathsFromFile /prefix
@@ -552,6 +652,8 @@ rec {
 
   /* Read the contents of a file removing the trailing \n
 
+     Type: fileContents :: path -> string
+
      Example:
        $ echo "1.0" > ./version