Skip to content

Leading whitespaces are preserved in a code span #4138

Open

Description

@sgrekhov

According to the Dart doc comment specification:

For each line that begins with ///, the parser removes the three slashes and all leading whitespace to produce the documentation text. Exception: inside fenced code blocks (```), whitespace after the leading /// is preserved to maintain code formatting.

The only exception is a fenced code blocks. But in case of code span (`) leading whitespaces are also preserved.
Example.

/// `
/// main() {
///   print('No leading whitespaces expected');
/// }
/// `

dart doc output is:

`
main() {
  print('No leading whitespaces expected');
}
`

The tests test_whitespaceInCodeSpan() in https://github.com/dart-lang/dartdoc/blob/main/test/co19/line_based_doc_comments_test.dart and test_whitespaceInCodeSpan() in https://github.com/dart-lang/dartdoc/blob/main/test/co19/block_based_doc_comments_test.dart fail.

Activity

  1. added
    type-bugIncorrect behavior (everything from a crash to more subtle misbehavior)
    on Dec 18, 2025
  2. self-assigned this
    on Dec 19, 2025
  3. sgrekhov commented on Jan 9, 2026

    @sgrekhov
    CollaboratorAuthor

    The same issue exists for block comments.

    /**
     * `
     * void main() {
     *   /// This line prints "Hello, world!"
     *   print('Hello, world!');
     * }
     * `
     */
    

    produces

    Expected: '`\n'
                'void main() {\n'
                '/// This line prints "Hello, world!"\n'
                'print(\'Hello, world!\');\n'
                '}\n'
                '`'
      Actual: '`\n'
                'void main() {\n'
                '  /// This line prints "Hello, world!"\n'
                '  print(\'Hello, world!\');\n'
                '}\n'
                '`'
    
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

type-bugIncorrect behavior (everything from a crash to more subtle misbehavior)

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions