Add support for nix

[jfly]

No description provided.

[elijah-potter]

Looks ready to merge. Before I do, does Nix need any additional support beyond this? For example, is there anything like JsDoc @tags for Nix?

[jfly]

Looks ready to merge. Before I do, does Nix need any additional support beyond this? For example, is there anything like JsDoc https://github.com/tags for Nix?

Yes, there's RFC 0145, which defines which comments are "doc-comments" and says that doc-comments are CommonMark. There's also nixdoc, which understands the RFC and documents the comment format.

It looks like Unit comment parser in harper already supports codefences.

I jut tried it out on some nixpkgs library code, and it doesn't seem to understand this :::{.example} ... ::: syntax. These are pandoc "fenced div", and nixpkgs documents its usage of these here.

So, tl;dr:

• RFC 0145 tells us that doc-comments start with /** and contain CommonMark.
• The largest nix project (nixpkgs) allows these doc-comments to contain pandoc fenced divs.
  • It might be fair to call this one of those "established conventions in the nix ecosystem" mentioned by RFC 0145.

So, how does this PR do?

• We're not detecting the difference between regular comments and doc-comments.
  • IMO, this is OK. Treating every comment as a doc-comment is fine for a spelling/grammar checking tool. This would be unacceptable behavior for a tool that generates documentation, but that's not Harper's job.
• We interpret all comments with harper's Unit parser when they really should be interpreted as CommonMark.
  • This might be nice to fix. Would we need a new comment_parser for this? Could we somehow leverage the existing Markdown parser?
• We don't understand pandoc "fenced divs".
  • I don't know what would be involved in this. I haven't been able to find a discussion about this over in our Markdown parser library.

IMO, the above imperfections are good enough for now.

[elijah-potter]

I completely agree. I just want to be aware of the limitations and have a written record of what needs to happen for "full" support. Thank you so much!