"Bold" headings (`**Heading**:`) have their initial asterisk chomped off
FireyFly opened this issue · comments
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..