adam-mcdaniel/oakc

doc subcommand markdown issues

kevinramharak opened this issue · 4 comments

kevinramharak commented

So i noticed a few issues with the doc subcommand:

  1. the -o OUTPUT flag does not seem to work
  2. characters like * and _ have special meaning in markdown. These characters are currently unescapable when writing a #[doc("*")] directive
  3. a function without arguments is printed out like fn HWI::comport_console_clear). A function with arguments is printed out correctly like fn HWI::comport_self_out(source: &char) -> bool.
adam-mcdaniel commented

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.

kevinramharak commented

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 \\\\*.

adam-mcdaniel commented

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.

adam-mcdaniel commented

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.