doc subcommand markdown issues

[kevinramharak]

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]

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]

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]

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]

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.