oakc
oakc copied to clipboard
doc subcommand markdown issues
So i noticed a few issues with the doc
subcommand:
- the
-o OUTPUT
flag does not seem to work - characters like
*
and_
have special meaning in markdown. These characters are currently unescapable when writing a#[doc("*")]
directive - a function without arguments is printed out like
fn HWI::comport_console_clear)
. A function with arguments is printed out correctly likefn HWI::comport_self_out(source: &char) -> bool
.
Ahh, the first problem came about when I fixed the -g
flag not working, and is a simple fix. Additionally, the third problem is also a one or two line fix. The second, however, I'm not really sure is a problem. The user has the ability to make the markdown look terrible by leaving an unescaped *
, and I'm fine with that being their fault.
Except it is impossible to escape it. Unless im writing the wrong sequence but from what i have tested nothing of the following will generate a *
: \*
, \\*
and \\\\*
.
Ohhhh, I see what you mean. I thought you meant that the user could not un-make-the-rest-of-the-markdown-italic. That should be fixed.
After doing some digging, the root of this problem is not in this crate. The crate printing the markdown to the terminal is at fault. If you want to display a *
character in your markdown, \*
will work. You just can't print it to the terminal properly right now; the -o
output file will be displayed properly by another markdown compiler or previewer.