From 06ac3fbebd4b6373e6d337d6b8c5aa5e5d61d5f6 Mon Sep 17 00:00:00 2001
From: Felix Buehler <account@buehler.rocks>
Date: Fri, 12 Sep 2025 16:16:41 +0200
Subject: [PATCH] lib/*: fix docs to use "returns" instead of "return"

---
 lib/attrsets.nix        | 10 +++++-----
 lib/deprecated/misc.nix |  4 ++--
 lib/fixed-points.nix    |  2 +-
 lib/lists.nix           | 22 +++++++++++-----------
 lib/modules.nix         | 12 ++++++------
 lib/options.nix         |  2 +-
 lib/path/default.nix    |  2 +-
 lib/strings.nix         |  8 ++++----
 lib/trivial.nix         |  6 +++---
 lib/types.nix           |  2 +-
 10 files changed, 35 insertions(+), 35 deletions(-)

diff --git a/lib/attrsets.nix b/lib/attrsets.nix
index b13a3f6ef637..8861ed9ef1c5 100644
--- a/lib/attrsets.nix
+++ b/lib/attrsets.nix
@@ -44,7 +44,7 @@ rec {
     ;
 
   /**
-    Return an attribute from nested attribute sets.
+    Returns an attribute from nested attribute sets.
 
     Nix has an [attribute selection operator `.`](https://nixos.org/manual/nix/stable/language/operators#attribute-selection) which is sufficient for such queries, as long as the number of attributes is static. For example:
 
@@ -111,7 +111,7 @@ rec {
     attrByPath' 0 set;
 
   /**
-    Return if an attribute from nested attribute set exists.
+    Returns if an attribute from nested attribute set exists.
 
     Nix has a [has attribute operator `?`](https://nixos.org/manual/nix/stable/language/operators#has-attribute), which is sufficient for such queries, as long as the number of attributes is static. For example:
 
@@ -177,7 +177,7 @@ rec {
     hasAttrByPath' 0 e;
 
   /**
-    Return the longest prefix of an attribute path that refers to an existing attribute in a nesting of attribute sets.
+    Returns the longest prefix of an attribute path that refers to an existing attribute in a nesting of attribute sets.
 
     Can be used after [`mapAttrsRecursiveCond`](#function-library-lib.attrsets.mapAttrsRecursiveCond) to apply a condition,
     although this will evaluate the predicate function on sibling attributes as well.
@@ -504,7 +504,7 @@ rec {
     updates: value: go 0 true value updates;
 
   /**
-    Return the specified attributes from a set.
+    Returns the specified attributes from a set.
 
     # Inputs
 
@@ -536,7 +536,7 @@ rec {
   attrVals = nameList: set: map (x: set.${x}) nameList;
 
   /**
-    Return the values of all attributes in the given set, sorted by
+    Returns the values of all attributes in the given set, sorted by
     attribute name.
 
     # Type
diff --git a/lib/deprecated/misc.nix b/lib/deprecated/misc.nix
index 22015c9b20aa..6cd8286d73d6 100644
--- a/lib/deprecated/misc.nix
+++ b/lib/deprecated/misc.nix
@@ -73,7 +73,7 @@ let
     name: default: attrs:
     attrs.${name} or default;
 
-  # Return the second argument if the first one is true or the empty version
+  # Returns the second argument if the first one is true or the empty version
   # of the second argument.
   ifEnable =
     cond: val:
@@ -89,7 +89,7 @@ let
     else
       null;
 
-  # Return true only if there is an attribute and it is true.
+  # Returns true only if there is an attribute and it is true.
   checkFlag =
     attrSet: name:
     if name == "true" then
diff --git a/lib/fixed-points.nix b/lib/fixed-points.nix
index e73cc7ec3dac..f4e06473e5ea 100644
--- a/lib/fixed-points.nix
+++ b/lib/fixed-points.nix
@@ -119,7 +119,7 @@ rec {
     x;
 
   /**
-    Return the fixpoint that `f` converges to when called iteratively, starting
+    Returns the fixpoint that `f` converges to when called iteratively, starting
     with the input `x`.
 
     ```
diff --git a/lib/lists.nix b/lib/lists.nix
index 3d324e545dd4..d42ce4079779 100644
--- a/lib/lists.nix
+++ b/lib/lists.nix
@@ -642,7 +642,7 @@ rec {
     if index == null then default else elemAt list index;
 
   /**
-    Return true if function `pred` returns true for at least one
+    Returns true if function `pred` returns true for at least one
     element of `list`.
 
     # Inputs
@@ -677,7 +677,7 @@ rec {
   any = builtins.any;
 
   /**
-    Return true if function `pred` returns true for all elements of
+    Returns true if function `pred` returns true for all elements of
     `list`.
 
     # Inputs
@@ -777,7 +777,7 @@ rec {
   optional = cond: elem: if cond then [ elem ] else [ ];
 
   /**
-    Return a list or an empty list, depending on a boolean value.
+    Returns a list or an empty list, depending on a boolean value.
 
     # Inputs
 
@@ -837,7 +837,7 @@ rec {
   toList = x: if isList x then x else [ x ];
 
   /**
-    Return a list of integers from `first` up to and including `last`.
+    Returns a list of integers from `first` up to and including `last`.
 
     # Inputs
 
@@ -871,7 +871,7 @@ rec {
   range = first: last: if first > last then [ ] else genList (n: first + n) (last - first + 1);
 
   /**
-    Return a list with `n` copies of an element.
+    Returns a list with `n` copies of an element.
 
     # Inputs
 
@@ -1429,7 +1429,7 @@ rec {
     map (x: elemAt x 1) (sort less prepared);
 
   /**
-    Return the first (at most) N elements of a list.
+    Returns the first (at most) N elements of a list.
 
     # Inputs
 
@@ -1463,7 +1463,7 @@ rec {
   take = count: sublist 0 count;
 
   /**
-    Return the last (at most) N elements of a list.
+    Returns the last (at most) N elements of a list.
 
     # Inputs
 
@@ -1639,7 +1639,7 @@ rec {
       throw "lib.lists.removePrefix: First argument is not a list prefix of the second argument";
 
   /**
-    Return a list consisting of at most `count` elements of `list`,
+    Returns a list consisting of at most `count` elements of `list`,
     starting at index `start`.
 
     # Inputs
@@ -1737,7 +1737,7 @@ rec {
     take commonPrefixLength list1;
 
   /**
-    Return the last element of a list.
+    Returns the last element of a list.
 
     This function throws an error if the list is empty.
 
@@ -1770,7 +1770,7 @@ rec {
     elemAt list (length list - 1);
 
   /**
-    Return all elements but the last.
+    Returns all elements but the last.
 
     This function throws an error if the list is empty.
 
@@ -1803,7 +1803,7 @@ rec {
     take (length list - 1) list;
 
   /**
-    Return the image of the cross product of some lists by a function.
+    Returns the image of the cross product of some lists by a function.
 
     # Examples
     :::{.example}
diff --git a/lib/modules.nix b/lib/modules.nix
index 3330579952de..96f306be00f7 100644
--- a/lib/modules.nix
+++ b/lib/modules.nix
@@ -1452,7 +1452,7 @@ let
   };
 
   /**
-    Return a definition with file location information.
+    Returns a definition with file location information.
   */
   mkDefinition = args@{ file, value, ... }: args // { _type = "definition"; };
 
@@ -1541,7 +1541,7 @@ let
     };
 
   /**
-    Return a module that causes a warning to be shown if the
+    Returns a module that causes a warning to be shown if the
     specified option is defined. For example,
 
       mkRemovedOptionModule [ "boot" "loader" "grub" "bootDevice" ] "<replacement instructions>"
@@ -1589,7 +1589,7 @@ let
     };
 
   /**
-    Return a module that causes a warning to be shown if the
+    Returns a module that causes a warning to be shown if the
     specified "from" option is defined; the defined value is however
     forwarded to the "to" option. This can be used to rename options
     while providing backward compatibility. For example,
@@ -1645,7 +1645,7 @@ let
     };
 
   /**
-    Return a module that causes a warning to be shown if any of the "from"
+    Returns a module that causes a warning to be shown if any of the "from"
     option is defined; the defined values can be used in the "mergeFn" to set
     the "to" value.
     This function can be used to merge multiple options into one that has a
@@ -1724,7 +1724,7 @@ let
 
   /**
     Single "from" version of mkMergedOptionModule.
-    Return a module that causes a warning to be shown if the "from" option is
+    Returns a module that causes a warning to be shown if the "from" option is
     defined; the defined value can be used in the "mergeFn" to set the "to"
     value.
     This function can be used to change an option into another that has a
@@ -1822,7 +1822,7 @@ let
   mkDerivedConfig = opt: f: mkOverride (opt.highestPrio or defaultOverridePriority) (f opt.value);
 
   /**
-    Return a module that help declares an option that has been renamed.
+    Returns a module that help declares an option that has been renamed.
     When a value is defined for the old option, it is forwarded to the `to` option.
   */
   doRename =
diff --git a/lib/options.nix b/lib/options.nix
index 637188d24d4f..cf5a8c0d62f7 100644
--- a/lib/options.nix
+++ b/lib/options.nix
@@ -499,7 +499,7 @@ rec {
     loc: defs:
     if defs == [ ] then
       abort "This case should never happen."
-    # Return early if we only have one element
+    # Returns early if we only have one element
     # This also makes it work for functions, because the foldl' below would try
     # to compare the first element with itself, which is false for functions
     else if length defs == 1 then
diff --git a/lib/path/default.nix b/lib/path/default.nix
index a03f6a04cafd..6736e7ab5beb 100644
--- a/lib/path/default.nix
+++ b/lib/path/default.nix
@@ -40,7 +40,7 @@ let
     isValid
     ;
 
-  # Return the reason why a subpath is invalid, or `null` if it's valid
+  # Returns the reason why a subpath is invalid, or `null` if it's valid
   subpathInvalidReason =
     value:
     if !isString value then
diff --git a/lib/strings.nix b/lib/strings.nix
index 359e1a4cd8db..942cc51bf394 100644
--- a/lib/strings.nix
+++ b/lib/strings.nix
@@ -1776,7 +1776,7 @@ rec {
     if len == 0 then [ (addContextFrom str "") ] else map (addContextFrom str) (go 0 "" [ ]);
 
   /**
-    Return a string without the specified prefix, if the prefix matches.
+    Returns a string without the specified prefix, if the prefix matches.
 
     # Inputs
 
@@ -1827,7 +1827,7 @@ rec {
       );
 
   /**
-    Return a string without the specified suffix, if the suffix matches.
+    Returns a string without the specified suffix, if the suffix matches.
 
     # Inputs
 
@@ -1878,7 +1878,7 @@ rec {
       );
 
   /**
-    Return true if string `v1` denotes a version older than `v2`.
+    Returns true if string `v1` denotes a version older than `v2`.
 
     # Inputs
 
@@ -1910,7 +1910,7 @@ rec {
   versionOlder = v1: v2: compareVersions v2 v1 == 1;
 
   /**
-    Return true if string v1 denotes a version equal to or newer than v2.
+    Returns true if string v1 denotes a version equal to or newer than v2.
 
     # Inputs
 
diff --git a/lib/trivial.nix b/lib/trivial.nix
index 7e4c5f549ee7..16dc2886ce88 100644
--- a/lib/trivial.nix
+++ b/lib/trivial.nix
@@ -307,7 +307,7 @@ in
     f b a;
 
   /**
-    Return `maybeValue` if not null, otherwise return `default`.
+    Returns `maybeValue` if not null, otherwise return `default`.
 
     # Inputs
 
@@ -509,7 +509,7 @@ in
   ## Integer operations
 
   /**
-    Return minimum of two numbers.
+    Returns minimum of two numbers.
 
     # Inputs
 
@@ -524,7 +524,7 @@ in
   min = x: y: if x < y then x else y;
 
   /**
-    Return maximum of two numbers.
+    Returns maximum of two numbers.
 
     # Inputs
 
diff --git a/lib/types.nix b/lib/types.nix
index 6b51f9254a00..f90c189b6fcd 100644
--- a/lib/types.nix
+++ b/lib/types.nix
@@ -289,7 +289,7 @@ let
     # `optionType`: The option type to parenthesize or not.
     #   The option whose description we're returning.
     #
-    # Return value
+    # Returns value
     #
     # The description of the `optionType`, with parentheses if there may be an
     # ambiguity.