In reply to @mcdonc:matrix.org
danielsidhion and bzm3r ... thank you for the PR review suggestions... I think all of them are incorporated except this one https://github.com/NixOS/nixpkgs/pull/277534/files#r1450744275 ... (heading name)... i rationalize why i think it's the right thing in a reply there

As I said in my review comments, this is looking really good, and if I had merge powers, I'd hit merge. But I also am not in touch with the details in a way that that infinisil or fricklerhandwerk might be, so it's a good thing I don't have merge powers.

Anyway I just want to say, as one new contributor to another, please don't feel frustrated by the fact that this is a process that will take time because both fricklerhandwerk and infinisil:

• are time constrained
• are careful, and therefore might have more requests for changes
• are human

I would suggest putting it up as a point for discussion in the meeting agenda for next week. It tends to get sorted out super fast in these meetings, because of the communication setup.

In the meantime I found it helpful to move onto other projects/PRs. I think of PRs as seeds that I plant...

As I said in my review comments, this is looking really good, and if I had merge powers, I'd hit merge. But I also am not in touch with the details in a way that that infinisil or fricklerhandwerk might be, so it's a good thing I don't have merge powers.

Anyway I just want to say, as one new contributor to another, in case you do find it frustrating (not sure): please don't feel (too) frustrated by the fact that this is a process that will take time because both fricklerhandwerk and infinisil:

• are time constrained
• are careful, and therefore might have more requests for changes
• are human

I would suggest putting it up as a point for discussion in the meeting agenda for next week. It tends to get sorted out super fast in these meetings, because of the communication setup.

In the meantime I found it helpful to move onto other projects/PRs. I think of PRs as seeds that I plant...

In reply to @bzzm3r:matrix.org
How feasible are such "docs auto-generation" projects, given the lack of typing systems or other automated verification/compiler-based checks in Nix-the-language?

As the author of rfc145 and the creator of https://noogle.dev i can say:

It is very much feasible to autogenerate documentation from doc-comments. At least the API descriptions of all functions in nixpkgs.

Roughly 95% of what is in Noogle currently could also be autogenerated by any other tool.

I think one of the next important steps is to migrate to "doc-comments" (/** {commonmark} */)

asymmetric I've briefly looked into nrd (nixos-render-docs), and opened this issue: https://github.com/NixOS/nixpkgs/issues/280514
See the reply of @pennae there. I dont fully understand yet how to change nrd to clear the path. I'd super thankfull if someone from the community could do it. Otherwise... it will take me quite while, because i'm super busy recently with work related stuff.

In reply to @johannes.kirschbauer:scs.ems.host

As the author of rfc145 and the creator of https://noogle.dev i can say:

It is very much feasible to autogenerate documentation from doc-comments. At least the API descriptions of all functions in nixpkgs.

Roughly 95% of what is in Noogle currently could also be autogenerated by any other tool.

I think one of the next important steps is to migrate to "doc-comments" (/** {commonmark} */)

asymmetric I've briefly looked into nrd (nixos-render-docs), and opened this issue: https://github.com/NixOS/nixpkgs/issues/280514
See the reply of @pennae there. I dont fully understand yet how to change nrd to clear the path. I'd super thankfull if someone from the community could do it. Otherwise... it will take me quite while, because i'm super busy recently with work related stuff.

But who does the work to ensure that the doc comments match up with the actual code?

Also, it seems the doc comments RFC left defining function arguments as "future work"...