Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Protect all blockquotes with norust #92

Open
coryan opened this issue Nov 5, 2024 · 0 comments
Open

Protect all blockquotes with norust #92

coryan opened this issue Nov 5, 2024 · 0 comments
Labels
generator Issues related to the code generator priority: p3 Desirable enhancement or fix. May not be included in next release. type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.

Comments

@coryan
Copy link
Contributor

coryan commented Nov 5, 2024

We need to parse the CommonMark comments and protect all block quotes with norust.

Background

The Protobuf and OpenAPI v3 documentation comments are in Markdown format, they are supposed to be (aip.dev/192) in CommonMark format, though sometimes they deviate from the AIP.

The generator converts these Protobuf comments into Rustdoc comments.

Rust tries to compile all blockquotes unless protected by a norust mark.

Block quotes appear in many different forms in the CommonMark spec.

In #57 I fixed block quotes protected by backticks (```), then I thought of other ways to specify block quotes.

Overview

We need to parse the CommonMark comments, apply changes in the syntax tree, and re-emit Markdown. Probably in the Codec's FormatDocComments() function. As a starting point, consider this Golang library: https://github.com/yuin/goldmark

Alternatives Considered

We could try to perform this cleanup using heuristics. Shudder. 😨

@coryan coryan added type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design. priority: p3 Desirable enhancement or fix. May not be included in next release. generator Issues related to the code generator labels Nov 5, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
generator Issues related to the code generator priority: p3 Desirable enhancement or fix. May not be included in next release. type: feature request ‘Nice-to-have’ improvement, new feature or different behavior or design.
Projects
None yet
Development

No branches or pull requests

1 participant