Extra detail in the documentation for "print"

[Hixie]

It would be great if we could add some more details to the documentation for "print":

https://master-api.flutter.dev/flutter/dart-core/print.html

...something like:

Flutter

In Flutter, print sends output to the application logs, e.g. on Android, those visible in adb logcat (as well as flutter run and flutter logs). This can be useful for debugging.

For permanent logging (e.g. verbose logging in a library, or extra debugging output printed in the event of unusual circumstances during development), consider using debugPrint instead of print, so that logs can be redirected. The [Timeline] feature in [dart:developer] may also be useful for purposes of tracing program activities.

In general, it is strongly recommended that release builds not produce any logs; they can leak sensitive information, distract developers of other applications that happen to also have this application on their device, and generally spend CPU cycles filling logs that are not seen by the user. The debugPrint property can be set to a no-op closure to disable logs (q.v.). A lint, avoid_print, can be turned on to flag any uses of print left during debugging.

[lrhn]

The print function is notoriously hard to document because it's entirely back-end defined. It's a request to make a string visible to the user in some way, mainly for debugging purposes, and that's all we can generally say.

We can then add some platform specific guides like "on the web, the string is written to the browser debug console", "in the stand-alone VM the string is written on standard output" and even "in Flutter ...." (and in whatever other platform might eventually exist). The problem with doing that is that is that its open-ended and we need to keep it in sync. Since the Dart platform library authors are not the ones writing Flutter's print implementation, we won't notice if the Flutter behavior changes, and there is a risk that the Flutter authors will forget to update the documentation too. I'm generally opposed to putting documentation in a place where it's not under the control of the person who can change the thing being documented. (Actually, I'm more opposed to something I need to change being under someone else's control than the other direction, so if you're fine with Flutter documentation being hard for you to update, we can probably work with that). It still feels wrong to have Flutter specific documentation in a non-Flutter repository. It talks about debugPrint, which doesn't even exist in the core Dart platform libraries, so we can't link to it. It introduces the notion of "release build" which isn't mentioned anywhere else. It just feels ... off.

Is there any (cheap and easy) way you can introduce Flutter specific documentation on the Dart platform libraries in the Flutter SDK, so that https://api.dart.dev/stable/2.13.4/dart-async/Zone/print.html would differ from https://api.flutter.dev/flutter/dart-async/Zone/print.html ? Even if it's just allowing the dartdoc tool to be configured with explicit overrides (which is something we could also use to document non-declaration types like dynamic, which is exported by dart:core, but not declared there).

[Hixie]

First of all, we're all just one team here, so I disagree with the premise of your concern. I have no problem with being granted commit access and submitting updates to core library documentation.

The print function is notoriously hard to document because it's entirely back-end defined. It's a request to make a string visible to the user in some way, mainly for debugging purposes, and that's all we can generally say.

The perfect is the enemy of the good here. It's much better for documentation to say "in this mode it does this, in that mode it does that, and you may be in a different mode that isn't documented" than to say nothing, which is what we do now.

The problem with doing that is that is that its open-ended and we need to keep it in sync.

Yup, that's our job.

Since the Dart platform library authors are not the ones writing Flutter's print implementation, we won't notice if the Flutter behavior changes, and there is a risk that the Flutter authors will forget to update the documentation too.

If it makes you feel any better, Flutter engineers also don't notice when Flutter documentation needs to be updated and Dart engineers also don't notice when Dart documentation needs to be updated. This is no different.

From the perspective of someone working on or using Flutter, all the Dart documentation is just as much part of Flutter's documentation as any "Flutter" documentation.

I'm generally opposed to putting documentation in a place where it's not under the control of the person who can change the thing being documented.

Let's make sure that we give control to those people then. :-)

(Actually, I'm more opposed to something I need to change being under someone else's control than the other direction, so if you're fine with Flutter documentation being hard for you to update, we can probably work with that).

I am fine with that. (I don't see why it would need to be any harder for me to update than for you to update, though.)

It still feels wrong to have Flutter specific documentation in a non-Flutter repository. It talks about debugPrint, which doesn't even exist in the core Dart platform libraries, so we can't link to it. It introduces the notion of "release build" which isn't mentioned anywhere else. It just feels ... off.

I think that ship has sailed. According to GitHub, there's 466 mentions of "Flutter" in this repo.

Is there any (cheap and easy) way you can introduce Flutter specific documentation on the Dart platform libraries in the Flutter SDK, so that https://api.dart.dev/stable/2.13.4/dart-async/Zone/print.html would differ from https://api.flutter.dev/flutter/dart-async/Zone/print.html ?

I think it would be a mistake for us to do this, because people Googling for documentation for Flutter will often end up in the "Dart" documentation and vice versa, and it would be much more useful for them if both of them gave full guidance and explained how they were related and so forth.

[lrhn]

We are trying to keep some level of separation/abstraction between different platforms. I can see why what we are doing now is not giving a good experience. I'm wary about adding Flutter-specific documentation directly to the platform library documentation because those docs are going to be read by people who're not using Flutter too. An Angular (or other non-Flutter) developer seeing documentation about what Flutter does is not being helped. If their platform isn't mentioned, they might even be more confused afterwards. That's why I'd prefer to for each platform to be able to have its own documentation overrides for functions where it matters, instead of having all of them in the same documentation (having one extra platform in the documentation sounds fine until it's the fourth or fifth platform - target platforms is essentially an open enum, so it shouldn't be ruled by a central registry). That still means that if you end up at the dart:core documentation, you don't see the documentation of the other platforms.

Maybe it's not a problem in practice, and just a matter of moderation. There can't be that many methods which behave vastly differently between platforms (they won't be that useful if they do). I'd expect dart:io and dart:async to have some potential differences, and then there's print.

Also, instead of doing the full documentation on the dart:core documentation of print, it could defer to Flutter-specific documentation, and be shorter:

On Flutter, the print function sends message to the application logs. The behavior of print can be configured using [debugPrint].(https://api.flutter.dev/flutter/foundation/debugPrint.html).

Then those links can give the full Flutter-specific documentation.

[Hixie]

Why can't we just also give detailed Angular and CLI documentation here? I don't understand the desire to underdocument. As far as I can tell it costs nothing, and is educational to the reader, who is only reading it because they want to be educated. Telling them more than they might need isn't bad, it's good, and makes them better prepared to take Dart into other environments later.

[Hixie]

It might be worth considering this in the context of other APIs that are different in Flutter and CLI Dart. For example, Isolate.spawnUri is not available in Flutter, but is still in the Flutter documentation (which I think is fine, though we should probably make it clearer what modes it is available in). Similarly, SendPort.send varies on web vs VM, but we currently don't really provide much colour there in the docs.

I think in all of these cases, as with print, we would benefit our users (all users, of all variants of Dart) by being explicit about all the variations in the docs, so that Flutter developers and CLI Dart developers and Dart-for-web developers and so on all get a full overview of the entire Dart ecosystem and how things fit together (or not).