Please, lets add documentation

Even for me sometimes it is still hard to navigate the source codebase.

One of the best ways to do good easy documentation - is to explain function argument constructors.

Using: https://github.com/haskell/haddock/blob/ghc-9.2/doc/cheatsheet/haddocks.pdf

Also, HLS allows to automatically create stubs for argument constructors.

-- Nix/Value.hs
-- ...

-- ** Monad

-- | @bind@
bindNValueF
  :: (Monad m, Monad n)
  => (forall x . n x -> m x) -- ^ Transform @n@ into @m@.
  -> (a -> n b) -- ^ A Kleisli arrow (see 'Control.Arrow.Kleisli' & Kleisli catagory).
  -> NValueF p m a -- ^ "Unfixed" (openly recursive) value of embedded Nix language.
  -> n (NValueF p m b) -- ^ An implementation of @transform (f =<< x)@ for embedded Nix language values.
bindNValueF transform f = \case
  NVConstantF a  -> pure $ NVConstantF a
  NVStrF      s  -> pure $ NVStrF s
  NVPathF     p  -> pure $ NVPathF p
  NVListF     l  -> NVListF <$> traverse f l
  NVSetF     p s -> NVSetF p <$> traverse f s
  NVClosureF p g -> pure $ NVClosureF p (transform . f <=< g)
  NVBuiltinF s g -> pure $ NVBuiltinF s (transform . f <=< g)

-- *** MonadTrans

-- ..

Now it is obvious what function does - mainly transform . f <=< g, traverse also known as traversing bind or something of that sorts.

I am generously accepting pretty much any word forms & documentation. As documentation is better than no documentation.

Also documentation: https://github.com/haskell-nix/hnix/issues/36

haskell-nix / hnix

Please, lets add documentation #1002