How to wrap long descriptions in a Flutter pubspec.yaml file?

I noticed that when using the Pubspec Assist plugin, it wraps the description line when updating a dependency.

description: Have you been turned into a newt? Would you like to be? This
  package can help. It has all of the newt-transmogrification functionality you
  have been looking for.

In researching this wrapping, I found that yaml supports wrapping, but indicates to use > (or | for keeping newlines, which probably isn't recommended for Flutter apps?).

The pubspec page on dart.dev shows an example using >-, but its own description doesn't mention anything about long descriptions or wrapping.

description: >-
  Have you been turned into a newt? Would you like to be?
  This package can help. It has all of the
  newt-transmogrification functionality you have been looking
  for.

Does it matter, in a Flutter project, say from an app store's perspective, which method is used for wrapping long descriptions in the pubspec.yaml file? I've always just kept them as one long line.

Solution

Wrapping is a YAML syntax feature. Flutter applies semantics to the parsed content of your YAML file.

This means that it doesn't matter to Flutter how you represent your YAML scalars, as long as the result – as defined by the YAML syntax you use – yields a valid value for Flutter.

With some scalars, YAML employs line folding: Single line breaks are transformed into a space, while empty lines are transformed into line breaks. This happens both with plain scalars and folded block scalars:

droggeljug: This is a plain scalar.
  It spans multiple lines but when parsed, contains a single line.

baked_beans: >-
  This is a folded block scalar.
  It also spans multiple lines.

  The previous empty line yields a line break in the parsed value.

There are some differences to consider:

plain scalars get ended by various special characters, such as : (when followed by whitespace). This should be obvious seeing that it forms an implicit key.
folded block scalars only end when content at the indentation of a parent node is encountered. You can savely write any character into a folded block scalar, even # which would otherwise starte a comment.
some scalars may be parsed a non-strings when given as plain scalar. For example, true might be a boolean and 42 might be a number. Folded block scalars always yield strings no matter the content.

Apart from these, there are also single- and double-quoted scalars, and literal block scalars (starting with | instead of >). Literal block scalars parse line breaks as-is. Double-quoted scalars parse escape sequences. Single-quoted scalars just don't end until the second ' is encountered. All of these scalar types may be multiline and all except literal block scalars do line folding. You can choose any of them to encode your string value.

As to the question which one you should use, I'd say the folded block scalar >- is the right tool for the job: You can write anything without worrying about YAML special characters, escape sequences, etc.