Underline feature of janet docstrings not worth it? #1591
Description
I'm considering if the appearance of docstrings at janet-lang.org might be improved [1]. As part of that process, I've been stuyding Janet's existing docstrings.
One thing I've noticed is that (I think) out of the hundreds of existing docstrings, there is only a single intended use of the underline feature (it's in the docstring for defdyn for the curious, for the word "must").
There are a number of places where the feature is triggered unintentionally though. This happens in the docstrings of filewatch/add and net/listen which have instances of "constant" names such as FILE_NOTIFY_CHANGE or SO_REUSEADDR:
Also, AFAIU, underlining is not part of (most?) Markdown flavors, nor is it part of CommonMark -- I mention this because the website docs mention "subset of Markdown" here and I do not see "underlining" there.
Could we consider removing the underlining feature?
That might make it less cumbersome to express docstrings like those of filewatch/add, which I think would otherwise require quite a lot of escaping of underscores. Additionally, when viewing the source code, it might be easier to read without so many backslashes [2].
[1] See the Rationale section of this for some background.
[2] Regarding readability, the following quote is apparently from the creator of Markdown:
The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible. The idea is that a Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.
via: https://daringfireball.net/projects/markdown/
Of course, just because that might have been one of the creator's design goals, that doesn't mean others have to adopt it. Just mentioning this point for reference.