Unable to markdown text if there are indents
Opened this issue · 5 comments
Unable to markdown text if there is a static indents before each line
//Bug
let str = """
Creates a personalized greeting for a recipient.
- Parameter recipient: The person being greeted.
- Throws: `MyError.invalidRecipient` if `recipient` is "Derek" (he knows what he did).
- Returns: A new string saying hello to `recipient`.
"""
//No problem
let str = """
Creates a personalized greeting for a recipient.
- Parameter recipient: The person being greeted.
- Throws: `MyError.invalidRecipient` if `recipient` is "Derek" (he knows what he did).
- Returns: A new string saying hello to `recipient`.
"""
I just did a quick test. The first example seems to be parsed as an indented code block - which is part of the spec, while the latter is parsed as a list. If you'd like both to be parsed as lists, then I believe the number of spaces in the first example should be less than four.
This is a result of Swift's syntax for multi-line string literals - the "beginning of the line" is determined by how indented the closing """ is. By having it so far over from the content, you're telling the Swift compiler to add all that leading indentation to the resulting string. If you want to have the string contents indented like the first sample, you need to also indent the closing delimiter:
let str = """
Creates a personalized greeting for a recipient.
- Parameter recipient: The person being greeted.
- Throws: `MyError.invalidRecipient` if `recipient` is "Derek" (he knows what he did).
- Returns: A new string saying hello to `recipient`.
"""What I do:
- I use SwiftSyntax to get docBlockComment text.
- This text contains the leading indents.
- I use
let document = Document(parsing: netCommentStr)to visit it and apply styling. - netCommentStr is the docBlockComment text after trimming
/**and*/
The main problem is that netCommentStr contains the leading indents.
Looks like I have to trim these indents before using it in Document parsing.
I would prefer that this problem be dealt automatically by ignoring leading indents.
Indented code blocks are a feature of basic Markdown; automatically stripping leading indentation would remove a foundational feature of Markdown syntax. This seems to be an issue in SwiftSyntax; all the reference documentation i could find about multi-line comments just says that the comment is the content between the /** and */ delimiters, without any reference to the indentation. I believe the compiler automatically strips this indentation before generating the symbol graph that is loaded by Swift-DocC, so i would expect SwiftSyntax to provide a similar mechanism.
I think we could exclude the indents according to leading indents in first line.
Example: If there is two tabs as leading indents in first line, we check if there is the same in each next line to exclude them all.
I beleave it is a "markdown" issue, because if there are repeated leading indents in each line, we just need to ignore them.
After that, the remaining leading indents are of cource useful.
