Skip to content

[specification] Whitespace in block comments in fenced code blocks #4160

@sgrekhov

Description

@sgrekhov

Please see 2.2. Block-Based Doc Comments (Historic, not recommended) of Dart documentation comment specification.

On each line after the opening /**, any leading whitespace followed by a single asterisk (*) is considered stylistic and is stripped by doc generators. Any whitespace immediately following the asterisk is also stripped, if present.

There is no exception for fenced code blocks (```). Therefore according to the current wording of the spec the comment like

/**
 * ```
 * main() {
 *   print('Hello world');
 * }
 * ```
 */

should produce documentation like

main() {
print('Hello world'!);
}

2.1. Line-Based Doc Comments contains:

Exception: inside fenced code blocks (```), whitespace after the leading /// is preserved to maintain code formatting.

The same exception should be made for Block-Based Doc Comments.

Metadata

Metadata

Assignees

Labels

type-documentationA request to add or improve documentation

Type

No type

Projects

No projects

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions