Dartdoc template names are inconsistent

[Hixie]

if you search for "@template" in the engine/src/flutter/lib/ui directory you'll find a variety of patterns:

window.dart
325:  /// {@template flutter.lib.ui.window.accessorForwardWarning}
592:  /// {@template flutter.lib.ui.window.functionForwardWarning}

text.dart
435:/// {@template flutter.dart:ui.textHeightBehavior}
1641:  /// {@template flutter.dart:ui.boxHeightStyle.includeLineSpacing}

painting.dart
22:/// {@template flutter.dart:ui.imageFormats}
4852:  /// {@template dart.ui.shadow.lerp}

compositing.dart
88:/// {@template dart.ui.sceneBuilder.oldLayerCompatibility}
258:  /// {@template dart.ui.sceneBuilder.oldLayer}
264:  /// {@template dart.ui.sceneBuilder.oldLayerVsRetained}

#platform_dispatcher.dart#
16:/// {@template dart.ui.TimingsCallback.list}
213:  /// {@template flutter.foundation.PlatformDispatcher.onBeginFrame}
240:  /// {@template flutter.foundation.PlatformDispatcher.onDrawFrame}
1137:  /// {@template dart.ui.FrameTiming.fps_smoothness_milliseconds}
1141:  /// {@template dart.ui.FrameTiming.fps_milliseconds}

platform_dispatcher.dart
16:/// {@template dart.ui.TimingsCallback.list}
213:  /// {@template flutter.foundation.PlatformDispatcher.onBeginFrame}
240:  /// {@template flutter.foundation.PlatformDispatcher.onDrawFrame}
1137:  /// {@template dart.ui.FrameTiming.fps_smoothness_milliseconds}
1141:  /// {@template dart.ui.FrameTiming.fps_milliseconds}

We should settle on one prefix for this library and use it consistently.

[gspencergoog]

I didn't even know you could use ":" in the name. :-) I suppose it's just a string in the end.

I propose it be standardized on dart.ui.class.symbol. Sound good?

The foundation one probably snuck in with copy/paste.

[Hixie]

I have no strong opinion one way or the other, all sounds good to me.

[pedromassangocode]

I remember seeing this exact same issue in the framework.
I suggest to expand this to the framework as well since currently there is no a standard and everyone is doing it differently.

I suggest the pattern bellow:
directory.filename.className.symbol

[gspencergoog]

Sounds good. I'll do it in the framework after the dart:ui change lands (since I need to do some work to update the framework to not use the macros I renamed here anyhow).

Instead of directory, I'd use library id (e.g. material, widgets, etc.), It would resolve to the same values, but be more clear as a policy, since the directory could include "lib", etc. Also, I'd prefix it with flutter to give it the package as namespace, as we typically do now. And we also need to allow for having multiple templates per symbol, so I'd add an optional "thing" at the end to accommodate that.

I do wonder if class name shouldn't just be the verbatim class name instead of an initial lowercase name, to make it easier to search for and easier to know what it refers to (and that it's a class name).

So:

package.library.filename.ClassName.symbol.thing

This means that a template on Navigator.pushNamed about the arguments would be:

flutter.widgets.navigator.Navigator.pushNamed.arguments

and just leave out components if they don't exist (e.g. for globals or symbols not in a library, or don't talk about a particular "thing").

This is also relatively in line with what most macros use already

[Hixie]

I wouldn't worry too much about being aggressively consistent about this, so long as related things have the same prefix. Having different macros in dart:ui start with wildly different prefixes is confusing, having all the navigator-related things called "flutter.widgets.navigator.*" even if they happen to be in routes.dart or in _NavigatorState or whatever is fine. It might even be clearer (and involve less churn as we move code around) to have the shorter product.library.area.macro format (and maybe product.area.macro for small libraries, and maybe product.library.area.group.macro when there's a lot of related macros). For example, right now all the flutter_test macros follow the flutter.flutter_test.macro format, and I don't think that's causing any harm, and Slider has a bunch of macros grouped together, which is probably clearer than if they weren't.

That said, we could definitely benefit from an audit to see if there's any cases where we're wildly inconsistent. Looking quickly I see a flutter.frame_rasterized_vs_presented macro in flutter_driver which could be scoped better, and input_decorator.dart has two templates, one in flutter.widgets and the other in flutter.material, which is a bit confusing. rendering/layer.dart also has some inconsistency in template naming. box_fit.dart has a template just called "clip_with_box_fit".

Anyway, I think the most valuable thing we could do here is document our intended patterns, more so than require rigorous adherence to a specific pattern.

[gspencergoog]

Yeah, I wasn't looking to write a new standards doc on it. I was just trying to figure out what the guidance should be.

[gspencergoog]

Things like this should probably be fixed, for sure: /// {@template FilterQuality} (from here).