doc: improve lib.options reference documentation

[hsjobeki]

Description of changes

• Migrate documentation of lib.options to rfc145
• Init documentation for many undocumented option functions

Things done

• Built on platform(s)
  • x86_64-linux
  • aarch64-linux
  • x86_64-darwin
  • aarch64-darwin
• For non-Linux: Is sandboxing enabled in nix.conf? (See Nix manual)
  • sandbox = relaxed
  • sandbox = true
• Tested, as applicable:
  • NixOS test(s) (look inside nixos/tests)
  • and/or package tests
  • or, for functions and "core" functionality, tests in lib/tests or pkgs/test
  • made sure NixOS tests are linked to the relevant packages
• Tested compilation of all packages that depend on this change using nix-shell -p nixpkgs-review --run "nixpkgs-review rev HEAD". Note: all changes have to be committed, also see nixpkgs-review usage
• Tested basic functionality of all binary files (usually in ./result/bin/)
• 24.11 Release Notes (or backporting 23.11 and 24.05 Release notes)
  • (Package updates) Added a release notes entry if the change is major or breaking
  • (Module updates) Added a release notes entry if the change is significant
  • (Module addition) Added a release notes entry if adding a new NixOS module
• Fits CONTRIBUTING.md.

---

Add a 👍 reaction to pull requests you find important.

[roberth]

Reviewed the first part. Ok overall, but noticed some quirks.

[roberth]

value is not part of the interface and isn't referenced anywhere in this documentation.

[roberth]

This should simply refer to mkOptionType. That's where all the merge functions are passed to, so it's the best place to describe the type of those functions.
Implementations don't have to repeat that, because they aren't actually called by users.

[hsjobeki]

I'd not move the documentation that is for this function into another place can we view it as a low level documentation? Maybe some Disclaimer:

This function is used as the default merge behavior in mkOptionType you should usually not need to use it yourself.

Currently most people see the following and i've not touched anything there.

# lib/types.nix
  /**
  
  */
  mkOptionType =
    {
    ...
    , # Merge a list of definitions together into a single value.
      # This function is called with two arguments: the location of
      # the option in the configuration as a list of strings
      # (e.g. ["boot" "loader "grub" "enable"]), and a list of
      # definition values and locations (e.g. [ { file = "/foo.nix";
      # value = 1; } { file = "/bar.nix"; value = 2 } ]).
      merge ? mergeDefaultOption

Since mergeDefaultOption is the default merge function we should describe its behavior here.
And we should describe the interface at the mkOptionType level. (Also place a link pointing here that explains the default merge behavior)

I'll also refactor the /lib/types.nix at a later point, so this comes together nicely.

Maybe I should add a concrete usage example:

    myType = mkOptionType {
      name = "myType";
      merge = mergeDefaultOption;
    };

[hsjobeki]

Just took a look into the nixpkgs manual. It seems we don't explain the concept of option types. At all.... (there)

[roberth]

Note to self: resume review here.

[hsjobeki]

@roberth big thanks for the review so far. The overall scope of this PR was to migrate the format to commonmark/markdown documentation.
But it somewhow evolved into cleaning up the entire documentation as i started to fix minor things 😀

[infinisil]

Just a small review, but note that this is a bit of a duplicate with https://nixos.org/manual/nixos/stable/#sec-option-declarations

We should really move those docs to the Nixpkgs manual, they don't belong into the NixOS one.

[hsjobeki]

We should really move those docs to the Nixpkgs manual, they don't belong into the NixOS one.

I could do a follow up PR, that moves them from the nixos manual into the nixpkgs manual and revise them with what we have here.

[hsjobeki]

@roberth @infinisil I've split and rebased the PR.

Everything you didn't came to review will be in a follow up PR. Feel free to merge this one if all issues are adressed.