lib/trivial: Move pipe note into pipe documentation. #105984
Conversation
This one is a little weird. The note at the end of the pipe function is being picked up by the documentation generator and being used as the documentation for the concat function (see the 20.09 manual for a cross reference). By moving this note into the documentation comment for pipe, we solve two issues: 1. the note being listed under concat where it doesn't belong 2. the documentation for concat actually being exposed in the manual If this isn't the desired solution we'll have to look into how documentation is generated and see if there is a bug in that system instead, but I like the clarity of this solution.
|
I think that is a bug in the documentation generator and that note is not intended to be exposed in the documentation – it is intended as a message for people who will edit the file in the future. |
|
That makes sense. I didn't know which way to take it since the note is useful in the manual as well (in fact, I'm wondering if most of these shouldn't be collapsed by default in the manual since they don't seem to be used for more than a reference when and if they're needed but I can handle that later). I'll see about setting up a new pull request that fixes the documentation generation to ensure it's only pulling comments that are attached to a function. Do you have any pointers on where to start looking into that? |
|
IIRC it should be somewhere in https://github.com/tazjin/nixdoc |
|
I marked this as stale due to inactivity. → More info |
stale
bot
added
the
2.status: stale
This one is a little weird. The note at the end of the pipe function is
being picked up by the documentation generator and being used as the
documentation for the concat function (see the 20.09 manual for a cross
reference). By moving this note into the documentation comment for
pipe, we solve two issues:
If this isn't the desired solution we'll have to look into how
documentation is generated and see if there is a bug in that system
instead, but I like the clarity of this solution.
Motivation for this change
Things done
sandboxinnix.confon non-NixOS linux)nix-shell -p nixpkgs-review --run "nixpkgs-review wip"./result/bin/)nix path-info -Sbefore and after)