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

Run of tildes in HTML comments confuses/reverses the at-directive parser #88

Open
amartini51 opened this issue Nov 11, 2022 · 1 comment

Comments

@amartini51
Copy link
Member

amartini51 commented Nov 11, 2022

The at-directive parser looks for runs of ~ or ` to delimit the start and end of code blocks. It knows that an at-directive can't start by @foo inside a code block. However, if one of those lines appears in an HTML comment, the at-directive parser doesn't ignore the line. This results in the "not in a code block" logic being inverted. For example, we ran into this issue in "The Swift Programming Language" (reduced example):

<!--
  Adding Child Tasks to a Task Group
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
  - Creating a group with ``withTaskGroup`` and ``withThrowingTaskGroup``
  
  - awaiting ``withGroup`` means waiting for all child tasks to complete
-->

```
struct NonsendableTemperatureReading {
    var measurement: Int
}

@available(*, unavailable)
extension NonsendableTemperatureReading: Sendable { }
```

In this case, @available is treated as the start of an at-directive and the code listing is mis-parsed and displays as follows:

199356359-535a8a12-6acd-4033-b709-82c45c38c6f1

rdar://101828693

amartini51 added a commit to amartini51/swift-book that referenced this issue Nov 11, 2022
The tildes look like the start of a fenced code block, inverting the
logic in DocC that knows at-directive blocks can't start in a code
listing, which in turn causes the @available in the non-sendable example
to be misparsed as the start of a directive.

Works around swiftlang/swift-markdown#88
@amartini51
Copy link
Member Author

Thanks to @QuietMisdreavus for investigating this issue with me!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant