escape character in dart comments

Question

I want to describe a half-opened period [start, end) in a comment where both, start and end refer to a parameter of a method:

/// Gets all items within period [[start],[end])

Which is displayed by intelij like this:

Using \ as escape character has the same problem:

What is the escape character in dart comments? The official documentation seems not to state how to escape the [ .

Answer 1

I don't know the escape character you're talking about, but you can add an extra pair of brackets after the single bracket you want to show:

/// Gets all items within period [[][start],[end])

It will look like this:

and when you hover your mouse over the method:

Answer 2

Normally square brackets denote identifiers that dartdoc should automatically generate links for. If you want literal square brackets in the generated documentation, you can escape them with a backslash:

/// Gets all items within period \[[start],[end])

For example, the following comment :

/// A fraction in the range \[0, 1\] that represents what proportion of the
/// widget is visible (assuming rectangular bounding boxes).

Generates: https://pub.dev/documentation/visibility_detector/latest/visibility_detector/VisibilityInfo/visibleFraction.html

Answer 3

I also need to comment brackets as part of a range.

I ended up escaping the whole line with 3 backticks (```)

The disadvantage is I cannot refer to any parameters/methods in that (code) comment, but on the bright side the comment is still very readable in the code.

If you need to refer the parameters, an extra line might be added to do this

Eg:

/// ```
/// Gets all items within period [start,end]
/// ```
///
/// The referred values are [start], [end]