doc: migrate filesets to doc-comment format

[hsjobeki]

Description of changes

lib.filesets comments migrated to doc-comments.

Manual steps:

• File description headings should start with h1 not h2. (consistency across doc-comments)
• reformatted some of the arguments/structured args documentation manually. Since they would be lost with our current automatism.

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.05 Release Notes (or backporting 23.05 and 23.11 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.

[DanielSidhion]

@hsjobeki I didn't make suggestions to fix the line indentation because I'm assuming you want to get these fixed in the tooling you're using for the conversion. The only suggestion I made is for a bit of extra content in the description of one of the functions, just because that function's description mentions two arguments, but only one is caught by the tooling.

[hsjobeki]

@DanielSidhion I'll add the indentation fixes to the tooling. Most of it was done manually anyways. I dont have tooling to automatically migrate structured arguments.
This is still an open question, so i did it by hand.

We must manually revise the file now. Migration cannot run twice. Maybe i should add a markdown formatter, but had bad experience in nixdoc with it. I'll think about the formatting issues.

[hsjobeki]

@DanielSidhion indentation should be fine now. (also needed to rebase)

[DanielSidhion]

Thanks for the changes! Also rendered the manual locally and checked that nothing was broken.