From 91154416b650e7a09c44b0c0d97399bc5c849117 Mon Sep 17 00:00:00 2001
From: Robert Helgesson <robert@rycee.net>
Date: Tue, 14 Nov 2017 18:59:27 +0100
Subject: [PATCH] docs: clarify package and module option naming

This attempts to briefly clarify the current naming conventions of
attribute names in `all-packages.nix` and module option names.
---
 doc/coding-conventions.xml                    | 25 ++++++++++---------
 .../development/option-declarations.xml       |  9 +++++++
 2 files changed, 22 insertions(+), 12 deletions(-)

diff --git a/doc/coding-conventions.xml b/doc/coding-conventions.xml
index 0776e70f14e..ec81c968e4a 100644
--- a/doc/coding-conventions.xml
+++ b/doc/coding-conventions.xml
@@ -18,9 +18,9 @@
   tab settings so it’s asking for trouble.</para></listitem>
 
   <listitem><para>Use <literal>lowerCamelCase</literal> for variable
-  names, not <literal>UpperCamelCase</literal>.  TODO: naming of
-  attributes in
-  <filename>all-packages.nix</filename>?</para></listitem>
+  names, not <literal>UpperCamelCase</literal>.  Note, this rule does
+  not apply to package attribute names, which instead follow the rules
+  in <xref linkend="sec-package-naming"/>.</para></listitem>
 
   <listitem><para>Function calls with attribute set arguments are
   written as
@@ -220,9 +220,10 @@ args.stdenv.mkDerivation (args // {
 
   <listitem><para>The variable name used for the instantiated package
   in <filename>all-packages.nix</filename>, and when passing it as a
-  dependency to other functions.  This is what Nix expression authors
-  see.  It can also be used when installing using <command>nix-env
-  -iA</command>.</para></listitem>
+  dependency to other functions.  Typically this is called the
+  <emphasis>package attribute name</emphasis>.  This is what Nix
+  expression authors see.  It can also be used when installing using
+  <command>nix-env -iA</command>.</para></listitem>
 
   <listitem><para>The filename for (the directory containing) the Nix
   expression.</para></listitem>
@@ -259,12 +260,12 @@ bound to the variable name <varname>e2fsprogs</varname> in
   Also append <literal>"unstable"</literal> to the name - e.g.,
   <literal>"pkgname-unstable-2014-09-23"</literal>.</para></listitem>
 
-  <listitem><para>Dashes in the package name should be preserved
-  in new variable names, rather than converted to underscores
-  (which was convention up to around 2013 and most names
-   still have underscores instead of dashes) — e.g.,
-  <varname>http-parser</varname> instead of
-  <varname>http_parser</varname>.</para></listitem>
+  <listitem><para>Dashes in the package name should be preserved in
+  new variable names, rather than converted to underscores or camel
+  cased — e.g., <varname>http-parser</varname> instead of
+  <varname>http_parser</varname> or <varname>httpParser</varname>.  The
+  hyphenated style is preferred in all three package
+  names.</para></listitem>
 
   <listitem><para>If there are multiple versions of a package, this
   should be reflected in the variable names in
diff --git a/nixos/doc/manual/development/option-declarations.xml b/nixos/doc/manual/development/option-declarations.xml
index be793152f9e..ed718c89eb7 100644
--- a/nixos/doc/manual/development/option-declarations.xml
+++ b/nixos/doc/manual/development/option-declarations.xml
@@ -22,6 +22,15 @@ options = {
 };
 </programlisting>
 
+The attribute names within the <replaceable>name</replaceable>
+attribute path must be camel cased in general but should, as an
+exception, match the
+<link
+xlink:href="https://nixos.org/nixpkgs/manual/#sec-package-naming">
+package attribute name</link> when referencing a Nixpkgs package. For
+example, the option <varname>services.nix-serve.bindAddress</varname>
+references the <varname>nix-serve</varname> Nixpkgs package.
+
 </para>
 
 <para>The function <varname>mkOption</varname> accepts the following arguments.