In reply to @raitobezarius:matrix.org
I know both codebases, I don't have deep familiarity with neither, but I can achieve deep familiarity with nrd in stupidly low amount of time

In reply to @infinisil:matrix.org
At least nixdoc is used already for lib documentation.

is there a plan to use nixdoc to document .override arguments/defaults, package doc comments, or function arguments?

# In `my-func/default.nix`
{ }: # ← callPackage arguments

/* I want this to render as documentation for `pkgs.my-func`
 */
{
/* I want this to render as documentation for `myArgument`
 */
myArgument
}:
null

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"...

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 how function arguments ought to be recorded in doc strings as "future work"...

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 how function arguments ought to be recorded in doc strings as "future work"...wouldn't that also be necessary for stuff like noogle, or auto-gen docs?

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this is might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

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

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

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

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```

bzm3r: You could also verify if your comments show up in noogle.

If you point noogle's "nixpkgs-master" flake input to your fork of nixpkgs and then execute nix build .#ui
You'll end up with the static site in ./result/lib/node_modules/noogle/out which you can serve statically with any http server. (e.g. nodePackages.http-server)

bzm3r: You could also verify if your comments show up in noogle.

If you point noogle's "nixpkgs-master" flake input to your fork of nixpkgs and then execute nix build .#ui
You'll end up with the static site in ./result/lib/node_modules/noogle/out which you can serve statically with any http server. (e.g. nodePackages.http-server)

Note: building takes quite a while the first time, because i modfiy c++ nix and the nix-build takes ~15minutes on my notebook)

In reply to @infinisil:matrix.org
No idea about the first, but the second one oh no..

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

bzm3r: > Also, it seems the doc comments RFC left defining how function arguments ought to be recorded in doc strings as "future work"...

I think this might be common missunderstanding:

We specified it for "lambda-formals".

#### Lambda formals

```nix
/**Doc for the whole lambda function*/
{
 /**Doc for formal 'a'*/
 a
}:
 a              
```