doc: add function argument order convention (#110060)

* doc: add function argument order convention

Ordering by usage is the de facto ordering given to arguments. It's
logical, and makes finding argument usage easier. Putting lib first is
common in NixOS modules, so it's reasonable to mirror this in nixpkgs
proper. Additionally, it's not a package as such, has zero dependencies,
and can be found used anywhere in a derivation.

* doc: clean up usage of lib

10 files changed, 30 insertions, 26 deletions

diff --git a/doc/contributing/coding-conventions.xml b/doc/contributing/coding-conventions.xml
index cb6d60c2c1384..9005a9ebafd63 100644
--- a/doc/contributing/coding-conventions.xml
+++ b/doc/contributing/coding-conventions.xml
@@ -180,6 +180,12 @@ args.stdenv.mkDerivation (args // {
    </listitem>
    <listitem>
     <para>
+     Arguments should be listed in the order they are used, with the
+     exception of <varname>lib</varname>, which always goes first.
+    </para>
+   </listitem>
+   <listitem>
+    <para>
      Prefer using the top-level <varname>lib</varname> over its alias
      <literal>stdenv.lib</literal>.  <varname>lib</varname> is unrelated to
      <varname>stdenv</varname>, and so <literal>stdenv.lib</literal> should only
diff --git a/doc/languages-frameworks/coq.section.md b/doc/languages-frameworks/coq.section.md
index 5e16a4c546a37..8f564c6e46b69 100644
--- a/doc/languages-frameworks/coq.section.md
+++ b/doc/languages-frameworks/coq.section.md
@@ -42,8 +42,8 @@ It also takes other standard `mkDerivation` attributes, they are added as such,
 Here is a simple package example. It is a pure Coq library, thus it depends on Coq. It builds on the Mathematical Components library, thus it also takes some `mathcomp` derivations as `extraBuildInputs`.
 
 ```nix
-{ coq, mkCoqDerivation, mathcomp, mathcomp-finmap, mathcomp-bigenough,
-  lib, version ? null }:
+{ lib, mkCoqDerivation, version ? null
+, coq, mathcomp, mathcomp-finmap, mathcomp-bigenough }:
 with lib; mkCoqDerivation {
   /* namePrefix leads to e.g. `name = coq8.11-mathcomp1.11-multinomials-1.5.2` */
   namePrefix = [ "coq" "mathcomp" ];
diff --git a/doc/languages-frameworks/idris.section.md b/doc/languages-frameworks/idris.section.md
index 2d06c4a19de51..41e4f7ec31279 100644
--- a/doc/languages-frameworks/idris.section.md
+++ b/doc/languages-frameworks/idris.section.md
@@ -69,11 +69,11 @@ prelude
 As an example of how a Nix expression for an Idris package can be created, here is the one for `idrisPackages.yaml`:
 
 ```nix
-{ build-idris-package
+{ lib
+, build-idris-package
 , fetchFromGitHub
 , contrib
 , lightyear
-, lib
 }:
 build-idris-package  {
   name = "yaml";
@@ -94,11 +94,11 @@ build-idris-package  {
     sha256 = "1g4pi0swmg214kndj85hj50ccmckni7piprsxfdzdfhg87s0avw7";
   };
 
-  meta = {
+  meta = with lib; {
     description = "Idris YAML lib";
     homepage = "https://github.com/Heather/Idris.Yaml";
-    license = lib.licenses.mit;
-    maintainers = [ lib.maintainers.brainrape ];
+    license = licenses.mit;
+    maintainers = [ maintainers.brainrape ];
   };
 }
 ```
diff --git a/doc/languages-frameworks/maven.section.md b/doc/languages-frameworks/maven.section.md
index 7a863c500bc37..d66931e808d71 100644
--- a/doc/languages-frameworks/maven.section.md
+++ b/doc/languages-frameworks/maven.section.md
@@ -116,7 +116,7 @@ The first step will be to build the Maven project as a fixed-output derivation i
 > Traditionally the Maven repository is at `~/.m2/repository`. We will override this to be the `$out` directory.
 
 ```nix
-{ stdenv, lib, maven }:
+{ lib, stdenv, maven }:
 stdenv.mkDerivation {
   name = "maven-repository";
   buildInputs = [ maven ];
@@ -168,7 +168,7 @@ If your package uses _SNAPSHOT_ dependencies or _version ranges_; there is a str
 Regardless of which strategy is chosen above, the step to build the derivation is the same.
 
 ```nix
-{ stdenv, lib, maven, callPackage }:
+{ stdenv, maven, callPackage }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -222,7 +222,7 @@ We will read the Maven repository and flatten it to a single list. This list wil
 We make sure to provide this classpath to the `makeWrapper`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 let
   repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
@@ -298,7 +298,7 @@ Main-Class: Main
 We will modify the derivation above to add a symlink to our repository so that it's accessible to our JAR during the `installPhase`.
 
 ```nix
-{ stdenv, lib, maven, callPackage, makeWrapper, jre }:
+{ stdenv, maven, callPackage, makeWrapper, jre }:
 # pick a repository derivation, here we will use buildMaven
 let repository = callPackage ./build-maven-repository.nix { };
 in stdenv.mkDerivation rec {
diff --git a/doc/languages-frameworks/ocaml.section.md b/doc/languages-frameworks/ocaml.section.md
index fa85a27e84f01..9b92a80f47123 100644
--- a/doc/languages-frameworks/ocaml.section.md
+++ b/doc/languages-frameworks/ocaml.section.md
@@ -32,11 +32,11 @@ buildDunePackage rec {
   propagatedBuildInputs = [ bigstringaf result ];
   doCheck = true;
 
-  meta = {
+  meta = with lib; {
     homepage = "https://github.com/inhabitedtype/angstrom";
     description = "OCaml parser combinators built for speed and memory efficiency";
-    license = lib.licenses.bsd3;
-    maintainers = with lib.maintainers; [ sternenseemann ];
+    license = licenses.bsd3;
+    maintainers = with maintainers; [ sternenseemann ];
   };
 }
 ```
diff --git a/doc/languages-frameworks/perl.section.md b/doc/languages-frameworks/perl.section.md
index 309d8ebcc2b39..dcb7dcb77b650 100644
--- a/doc/languages-frameworks/perl.section.md
+++ b/doc/languages-frameworks/perl.section.md
@@ -110,7 +110,7 @@ ClassC3Componentised = buildPerlPackage rec {
 On Darwin, if a script has too many `-Idir` flags in its first line (its “shebang line”), it will not run. This can be worked around by calling the `shortenPerlShebang` function from the `postInstall` phase:
 
 ```nix
-{ stdenv, lib, buildPerlPackage, fetchurl, shortenPerlShebang }:
+{ lib, stdenv, buildPerlPackage, fetchurl, shortenPerlShebang }:
 
 ImageExifTool = buildPerlPackage {
   pname = "Image-ExifTool";
diff --git a/doc/languages-frameworks/qt.section.md b/doc/languages-frameworks/qt.section.md
index 6cfdc66355064..5dd415852c100 100644
--- a/doc/languages-frameworks/qt.section.md
+++ b/doc/languages-frameworks/qt.section.md
@@ -8,7 +8,7 @@ There are primarily two problems which the Qt infrastructure is designed to addr
 
 ```{=docbook}
 <programlisting>
-{ mkDerivation, lib, qtbase }: <co xml:id='qt-default-nix-co-1' />
+{ mkDerivation, qtbase }: <co xml:id='qt-default-nix-co-1' />
 
 mkDerivation { <co xml:id='qt-default-nix-co-2' />
   pname = "myapp";
diff --git a/doc/languages-frameworks/r.section.md b/doc/languages-frameworks/r.section.md
index 32a39ade27965..c420d112c91e9 100644
--- a/doc/languages-frameworks/r.section.md
+++ b/doc/languages-frameworks/r.section.md
@@ -32,14 +32,12 @@ However, if you'd like to add a file to your project source to make the
 environment available for other contributors, you can create a `default.nix`
 file like so:
 ```nix
-let
-  pkgs = import <nixpkgs> {};
-  stdenv = pkgs.stdenv;
-in with pkgs; {
+with import <nixpkgs> {};
+{
   myProject = stdenv.mkDerivation {
     name = "myProject";
     version = "1";
-    src = if pkgs.lib.inNixShell then null else nix;
+    src = if lib.inNixShell then null else nix;
 
     buildInputs = with rPackages; [
       R
diff --git a/doc/languages-frameworks/ruby.section.md b/doc/languages-frameworks/ruby.section.md
index e292b3110ff4c..aeec154586c70 100644
--- a/doc/languages-frameworks/ruby.section.md
+++ b/doc/languages-frameworks/ruby.section.md
@@ -232,7 +232,7 @@ If you want to package a specific version, you can use the standard Gemfile synt
 Now you can also also make a `default.nix` that looks like this:
 
 ```nix
-{ lib, bundlerApp }:
+{ bundlerApp }:
 
 bundlerApp {
   pname = "mdl";
diff --git a/doc/languages-frameworks/rust.section.md b/doc/languages-frameworks/rust.section.md
index 550f2b576bd93..8f6db28ab4d63 100644
--- a/doc/languages-frameworks/rust.section.md
+++ b/doc/languages-frameworks/rust.section.md
@@ -19,6 +19,8 @@ or use Mozilla's [Rust nightlies overlay](#using-the-rust-nightlies-overlay).
 Rust applications are packaged by using the `buildRustPackage` helper from `rustPlatform`:
 
 ```
+{ lib, rustPlatform }:
+
 rustPlatform.buildRustPackage rec {
   pname = "ripgrep";
   version = "12.1.1";
@@ -226,8 +228,6 @@ source code in a reproducible way. If it is missing or out-of-date one can use
 the `cargoPatches` attribute to update or add it.
 
 ```
-{ lib, rustPlatform, fetchFromGitHub }:
-
 rustPlatform.buildRustPackage rec {
   (...)
   cargoPatches = [
@@ -263,7 +263,7 @@ Now, the file produced by the call to `carnix`, called `hello.nix`, looks like:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in
@@ -292,7 +292,7 @@ following nix file:
 
 ```
 # Generated by carnix 0.6.5: carnix -o hello.nix --src ./. Cargo.lock --standalone
-{ lib, stdenv, buildRustCrate, fetchgit }:
+{ stdenv, buildRustCrate, fetchgit }:
 let kernel = stdenv.buildPlatform.parsed.kernel.name;
     # ... (content skipped)
 in