doc: migrate trivial files to doc-comment format

[hsjobeki]

Description of changes

Some files in /lib are trivial to migrate to doc-comments. Those are included here.

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.

[hsjobeki]

Reading through the types.nix file. I just notice how bad the module system types are documented. This could be something very impactful to document!

[lolbinarycat]

it looks as though this is just a string replacement of /* with /**.

remember, documentation that is only relevant to nixpkgs contributors does not belong in the manual.

and commented out code defiantly does not belong in the manual.

[hsjobeki]

Oops. Right you are talking about test/misc.nix.
It is a little more than just a string replacement. Also a migration to Markdown/Commonmark.

This PR belongs to this one: #262987 there it is obvious that it is not just a string replacement.

[lolbinarycat]

doc comments can be useful, but i would also like to note a few things:

1. overuse of individual function doc comments can lead to lower quality documentation that never explains the operation of the library as a whole
2. markdown-formatted doc comments are harder for editors to perform syntax highlighting on than external markdown documentation

i think the best approach is to have doc comments be supplemental to the existing nix manual, instead of replacing it.

additionally, you seem to have turned a few file-header comments into doc comments, and it's not clear how or if these should be rendered into the manual (probably not, since they mostly explain implementation details)

[hsjobeki]

👍 Noted.

you seem to have turned a few file-header comments into doc comments, and it's not clear how or if these should be rendered into the manual

We have the tools to render them in the manual currently. see e.g.:
https://nixos.org/manual/nixpkgs/stable/#sec-functions-library-strings
-> "String manipulation functions."

This stems from the "file header" of lib/strings.nix.

For 2. see my (draft) PR: nix-community/nixdoc#114

Yes, markdown has bad support when being inlined but i feel like this is something we have to deal with. Since rfc74 all nix documentation is markdown. And since rfc145 all doc-comments are markdown.

We still need to decide which comments are doc-comments which is the fair point you got here.

overuse of individual function doc comments can lead to lower quality documentation that never explains the operation of the library as a whole.

Doc-comments explain individual functions or attributes or pieces of code that are user facing APIs. They are not meant to explain the whole library or abstract concepts. If that is missing then we need to write it. And this might not be something a doc-comment can do for you.

[infinisil]

Reading through the types.nix file. I just notice how bad the module system types are documented. This could be something very impactful to document!

lib.types are decently documented, just in the NixOS manual: https://nixos.org/manual/nixos/stable/#sec-option-types

It would be great to move the doc source into doc comments!

[hsjobeki]

Reading through the types.nix file. I just notice how bad the module system types are documented. This could be something very impactful to document!

lib.types are decently documented, just in the NixOS manual: https://nixos.org/manual/nixos/stable/#sec-option-types

It would be great to move the doc source into doc comments!

Right didn't look there. I'll try to move the stuff in a separate PR.

[DanielSidhion]

LGTM, just a couple adjustments needed imo, but feel free to consider it approved after they're dealt with.

[infinisil]

(reviewed during the docs team meeting)

Looking good!

[nixos-discourse]

This pull request has been mentioned on NixOS Discourse. There might be relevant details there:

https://discourse.nixos.org/t/2024-04-04-documentation-team-meeting-notes-117/42754/1