Poor handling of adjacent strings in annotations

[bwilkerson]

The @Deprecated(...) annotation takes a string that describes what to use in place of the deprecated element. When that string is long, authors will sometimes use adjacent strings to break it up to fit within the line length. This doesn't look very good.

We should consider merging the contents of the adjacent strings into a single string and displaying it as if it hadn't been broken up into separate chunks.

For an example, see the child parameter from https://api.flutter.dev/flutter/material/showDialog.html. As of this writing it currently displays as

Future<T> showDialog <T>(
    {@required BuildContext context,
    WidgetBuilder builder,
    bool barrierDismissible: true,
    Color barrierColor,
    bool useSafeArea: true,
    bool useRootNavigator: true,
    RouteSettings routeSettings,
    @Deprecated('Instead of using the "child" argument, return the child from a closure ' 'provided to the "builder" argument. This will ensure that the BuildContext ' 'is appropriate for widgets built in the dialog. ' 'This feature was deprecated after v0.2.3.') Widget child}
)

(Also, the text for the useSafeArea parameter appears to be missing a backtick at one point, messing up the fonts used. It might be useful to have a check for unbalanced backticks in the markdown to help catch bugs like this.)

[jcollins-g]

Yeah, this is ugly. (P3 only because triage priority says that for minor display warts like this). This seems like it should be fixable.

[srawlins]

This is tricky because the components may differ in their string delimiter (' vs " vs ''' vs """) and rawness (with or without r). Here's an example from in_app_purchase_android: