swiftlang/swift-markdown

Including a @Comment in silently breaks symbol's doc rendering

Closed this issue · 5 comments

ktoso commented

Description

Let's say I have a symbol Example.

In my Sources/ExampleThing/ExampleThing.docc/Example.md i have

# ``Example``

@Comment { Don't forget X }

## More things here

Lorem ipsum...

This silently breaks the rendering of the entire page's rendering -- it appears completely empty and no warnings are emitted either.

I'm guessing @Comment can only be used in a tutorial -- which is a bit meh... the syntax should be the same in al types of files.

Checklist

  • If possible, I've reproduced the issue using the main branch of this package.
  • This issue hasn't been addressed in an existing GitHub issue.

Expected Behavior

The @comment should work as expected -- just not be rendered.

Actual behavior

The rendering of the entire documentation page for the symbol is empty / broken by the presence of a @Comment

Steps To Reproduce

  • document any symbol
  • add @Comment { hello }
  • observe the comment prevented content, other than the sub-title from being rendered

Swift-DocC Version Information

5.7

Swift Compiler Version Information

-> % swift --version
swift-driver version: 1.62.1 Apple Swift version 5.7 (swiftlang-5.7.0.123.6 clang-1400.0.29.50)
QuietMisdreavus commented

There's a known issue about directives on one line (rdar://79629220). The parser doesn't currently recognize that the directive is closed if it's closed on the same line it's declared. If you break it into multiple lines, the rest should render:

# ``Example``

@Comment {
    Don't forget X
}

## More things here

Lorem ipsum...
ktoso commented

I can confirm the workaround works and we've worked around this in apple/swift-distributed-actors#1027 for now.

Kyle-Ye commented

Update:
The Article will be properly parsed at some time as the following after #66, but still renders the wrong output.
I'm digging it to find more info.

# Example

@Comment { Don't forget X }

asdfsda

## More things here

Lorem ipsum...

Document
├─ Heading level: 1
│  └─ Text \"Example\"
├─ BlockDirective name: \"Comment\"
│  └─ Paragraph
│     └─ Text \"Don’t forget X\"
├─ Paragraph
│  └─ Text \"asdfsda\"
├─ Heading level: 2
│  └─ Text \"More things here\"
└─ Paragraph
   └─ Text \"Lorem ipsum\"
Kyle-Ye commented

I checked the JSON presentation of the following 3 forms in a docc's markdown file. (DemoKit.docc/.docc-build/data/documentation/demokit.json)

The JSONs seems to be identical(under #66). But the render output for case 1 is not correct(described as the issue above), and for case 2 and 3 they are correct both on Xcode and swift-docc-render.

Could anybody help confirm this? cc @QuietMisdreavus

// Case 1
# ``DemoKit``

hello

@Comment { Don't forget X }

world

// Case 2
# ``DemoKit``

hello

<!--@Comment { Don't forget X }-->

world

// Case 3
# ``DemoKit``

hello

world

demokit.json.zip

By the way, I think the issue is not a swift-markdown issue anymore. Maybe we should transform it once the conclusion is clear.

Kyle-Ye commented

Also in case 2, the Xcode's rendering looks like a bug for me.

I've filed it to Apple's Feedback as FB11157755.

image