[Nix-dev] Request for Doc: how about doxygenize Nixpkgs

[Marc Weber]

Let's first talk about pro/cons (eg comparing with wiki)

  + always in sync with nixpkgs
  + if you grep for words you'll find both: code/docs and update both

(but this also applies to simple comments).

For those reasons I'd like to see such.

But what is the exact reason asking for doxygen like docs? Having a nice
HTML view of the documentation only?

I don't think we should get started with adding trivial comments like

  /*** this derivation builds vim ***/
  vim = mkDerivation ...

which can be seen by looking at the code. This is because usually I'm
against duplication (others might think differently).

I guess that you know about the official documentation.

For nixos we have "doxygenized" documentation about configuration
options only, but not for code. I'm pretty sure we want to keep that for
"man configuration.nix" like reasons.

eg lib/** is already documented nicely, If you want to find docs faster
I recommend tagging the sources, see
https://nixos.org/wiki/Howto_find_a_package_in_NixOS
headline "Indexing and searching Nix files"

When asking for doxygenize you should focus on talking about
what you were missing to clarify why you want it exactly.

Marc Weber