Giters

lf- / nix-doc

An interactive Nix documentation tool providing a CLI for function search, a Nix plugin for docs in the REPL, and a ctags implementation for Nix script

Geek Repo:Geek Repo

Github PK Tool:Github PK Tool

"Bold" headings (`**Heading**:`) have their initial asterisk chomped off

FireyFly opened this issue · comments

commented

There are a few places in nixpkgs lib where **Foo**: is used as a heading instead of the usual markdown # Foo ones. I think this is intentional with how it gets rendered in the manual, e.g. lib.lists.sortOn.

nix-doc prints this as

   *Laws**:
       ```nix
       sortOn f == sort (p: q: f p < f q)
       ```

chomping off the first asterisk as part of cleanup_single_line that's meant to deal with /** \n * \n * \n */ style doc comments. This also means the usage in lix ends up funny-looking with a trailing asterisk as if there's a footnote to pay attention to (which is how I first noticed it, heh)

I think it'd be enough to just check for a space after the asterisk before doing the line chomping probably?

Honestly I think it's debatable whether the three occurrences (lib.sortOn, lib.hashAttrByPath, lib.fix) of this in nixpkgs outside of <nixpkgs/nixos> should stay an exception or just change their headings, but I figure either way it's a (minor) parsing bug in nix-doc..