diff options
| -rw-r--r-- | doc/coding-conventions.xml | 46 |
1 files changed, 46 insertions, 0 deletions
diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml index 3e4afdc1d4f5..586fcd98f23d 100644 --- a/doc/coding-conventions.xml +++ b/doc/coding-conventions.xml @@ -156,6 +156,52 @@ stdenv.mkDerivation { ... </para></listitem> + <listitem><para>Functions should list their expected arguments as + precisely as possible. That is, write + +<programlisting> +{ stdenv, fetchurl, perl }: <replaceable>...</replaceable> +</programlisting> + + instead of + +<programlisting> +args: with args; <replaceable>...</replaceable> +</programlisting> + + or + +<programlisting> +{ stdenv, fetchurl, perl, ... }: <replaceable>...</replaceable> +</programlisting> + + </para> + + <para>For functions that are truly generic in the number of + arguments (such as wrappers around <varname>mkDerivation</varname>) + that have some required arguments, you should write them using an + <literal>@</literal>-pattern: + +<programlisting> +{ stdenv, doCoverageAnalysis ? false, ... } @ args: + +stdenv.mkDerivation (args // { + <replaceable>...</replaceable> if doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable> +}) +</programlisting> + + instead of + +<programlisting> +args: + +args.stdenv.mkDerivation (args // { + <replaceable>...</replaceable> if args ? doCoverageAnalysis && args.doCoverageAnalysis then "bla" else "" <replaceable>...</replaceable> +}) +</programlisting> + + </para></listitem> + </itemizedlist> </section> |