@@ -42,18 +42,27 @@ system.
4242
4343## Haskell Package description
4444
45−Options for building a package. (todo: more info)
45+The _Haskell package descriptions_ are values of the
46+`pkgSet.config.packages` attrset. These are not derivations, but just
47+the configuration for building an individual package. The
48+configuration options are described under `packages.<name>` in [Module
49+options](./modules.md).
4650
4751## Component description
4852
49−Options for building a component. (todo: more info)
53+The _component descriptions_ are values of the
54+`pkgSet.config.packages.<package>.components` attrset. These are not
55+derivations, but just the configuration for building an individual
56+component. The configuration options are described under
57+`packages.<name>.components.*` in [Module options](./modules.md).
58+
5059
5160## Haskell Package
5261
53−A derivation which has a `components` attribute. This derivation is
54−actually just for the package `Setup.hs` script, and isn't very
55−interesting. To actually use the package, look within the components
56−structure.
62+In [Haskell.nix][], a _Haskell package_ is a derivation which has a
63+`components` attribute. This derivation is actually just for the
64+package `Setup.hs` script, and isn't very interesting. To actually use
65+the package, look within the components structure.
5766
5867```
5968components = {
@@ -67,14 +76,44 @@ components = {
6776
6877## Component
6978
79+In [Haskell.nix][], a _component_ is a derivation corresponding to a
80+[Cabal component](https://www.haskell.org/cabal/users-guide/developing-packages.html)
81+of a package.
82+
83+[Haskell.nix][] also defines a special `all` component, which is the
84+union of all components in the package.
85+
7086## Identifier
7187
7288A package identifier is an attrset pair of `name` and `version`.
7389
7490## Extras
7591
92+Extras allow adding more packages to the package set. These will be
93+functions taking a single parameter `hackage`. They should return an
94+attrset of package descriptions.
95+
7696## Modules
7797
98+Modules are the primary method of configuring building of the package
99+set. They are either:
100+
101+1. an attrset containing [option declarations](./options.md), or
102+2. a function that returns an attrset containing option declarations.
103+
104+If using the function form of a module, the following named parameters
105+will be passed to it:
106+
107+| Argument | Type | Description |
108+|------------------|------|---------------------|
109+| `haskellLib` | attrset | The [haskellLib](#haskelllib) utility functions. |
110+| `pkgs` | | The Nixpkgs collection. |
111+| `pkgconfPkgs` | | A mapping of cabal build-depends names to Nixpkgs packages. (TODO: more information about this) |
112+| `buildModules` | | |
113+| `config` | | |
114+| `options` | | |
115+
116+
78117# Top-level attributes
79118
80119## mkStackPkgSet
@@ -126,7 +165,11 @@ This is an attrset of `hsPkgs` packages from Stackage.
126165
127166## haskellPackages
128167
129−A `hsPkgs` package set
168+A `hsPkgs` package set, which is one of the recent LTS Haskell
169+releases from [`snapshots`](#snapshots).
170+
171+The chosen LTS is updated occasionally in [Haskell.nix][], though a
172+manual process.
130173
131174## nix-tools
132175
@@ -145,6 +188,10 @@ A derivation containing the `nix-tools` [command-line tools](commands.md).
145188
146189## haskellLib
147190
191+Assorted functions for operating on [Haskell.nix][] data. This is
192+distinct from `pkgs.haskell.lib` in the current Nixpkgs Haskell
193+Infrastructure.
194+
148195# Package-set functions
149196
150197These functions exist within the `hsPkgs` package set.
@@ -152,8 +199,8 @@ These functions exist within the `hsPkgs` package set.
152199## shellFor
153200
154201Create a `nix-shell` [development
155−environment](../user-guide/development.md) *for* developing one or
156−more packages.
202+environment](../user-guide/development.md) for developing one or more
203+packages.
157204
158205```
159206shellFor =
@@ -171,7 +218,24 @@ shellFor =
171218
172219## ghcWithPackages
173220
221+Creates a `nix-shell` [development
222+environment](../user-guide/development.md) including the given
223+packages selected from this package set.
224+
225+**Parameter**: a package selection function.
226+
227+**Return value**: a derivation
228+
229+**Example**:
230+
231+```
232+haskell.haskellPackages.ghcWithPackages (ps: with ps; [ lens conduit ])
233+```
234+
174235## ghcWithHoogle
175236
237+The same as `ghcWithPackages`, except, a `hoogle` command with a
238+Hoogle documentation index of the packages will be included in the
239+shell.
176240
177241[haskell.nix]: https://github.com/input-output-hk/haskell.nix