Underscores in function names mistaken for formatting in docgen

[Theodus]

For example, the documentation for AppDirs.user_data_dir shows as "user data dir" (https://www.main.actor/packages/appdirs/0.1.0/appdirs/appdirs)

[EpicEric]

This also happens for the "Parameters" section.

[EpicEric]

This is because of how ponyc --docs generates Markdown, as it should escape underscores in both of these cases -- but doesn't.

[SeanTAllen]

This works fine with stdlib. So mkdocs handles this.

Should we consider this to be a bug in pony documentation generation (that it doesn't escape any markdown special characters?) or in main.actor?

I mostly want to say this is a main.actor issue Technically the markdown should be set_notify. not set_notify. But the former isn't exactly readable as plain text which is one of the key goals of markdown.

@EpicEric @Theodus input?

[EpicEric]

This is definitely a docgen problem. There are already parts of the document being properly escaped, such as generic types. This part, for example, shows both:

### from_iso_array
<span class="source-link">[[Source]](src/builtin/string.md#L71)</span>

Create a string from an array, reusing the underlying data pointer

[... removed codeblock in clodeblock because it breaks this example ...]

#### Parameters

*   data: [Array](builtin-Array.md)\[[U8](builtin-U8.md) val\] iso

#### Returns

* [String](builtin-String.md) iso^

The only reason this doesn't break for https://stdlib.ponylang.io is because MkDocs tries to be "smart" and doesn't treat multiple underlines in the same word as emphasis.

---

CommonMark (which is the closest thing we have to a Markdown spec) says that "Emphasis with _ is not allowed inside words" (spec | example). Which would mean that MkDocs is correct here, and main.actor isn't.

Personally, I'd err on the side of compatibility and escape these characters, since we cannot guarantee that users' Markdown implementations will follow CommonMark. But I have no strong preference about fixing it only for main.actor and keeping docgen as-is.

[SeanTAllen]

@EpicEric I'm of the opinion that in the next documentation generation system (which will be coming eventually), we shouldn't be generating markdown documents, which could render this somewhat moot.

[SeanTAllen]

If we "fixed" main.actor, it would fix all the documentation on main.actor. If we fix docgen, then it will fix all documentation going forward.

[SeanTAllen]

@EpicEric main.actor is using remark which should be using commonmark. Which makes me think that we should be addressing on the main.actor side for now. It would appear to be an issue there.

[SeanTAllen]

@ChristopherBiscardi main.actor is using commonmark via remark, so this shouldn't, in theory, be happening, correct?

[EpicEric]

@EpicEric main.actor is using remark which should be using commonmark. Which makes me think that we should be addressing on the main.actor side for now. It would appear to be an issue there.

Okay, moving the issue back.