Formalize warnings

[annevk]

Often specifications want to give hints at things that can be reported to a developer console, if there is any. Should we formalize that in the Console Standard?

(I was looking at fixing whatwg/fetch#259 and then I wondered whether we should have some shared mechanism across specifications.)

[terinjokes]

I like this idea, but wouldn't know where to begin in integrating it here.

[domenic]

So if you search through https://html.spec.whatwg.org/ (not the multipage version) for "developer console", it comes up a few times:

If the error is still not handled after this, then the error may be reported to a developer console.

(and several similar phrases in various points)

If any of the objects in transfer are the target port, if any, then let doomed be true, and optionally report to a developer console that the target port was posted to itself, causing the communication channel to be lost.

If the value doesn't compile successfully, user agents are encouraged to log this fact in a developer console, to aid debugging.

User agents are encouraged to log the precise cause in a developer console, to aid debugging.

(although that section will be going away soon per whatwg/html#1207)

If any value in a is not finite (e.g. an Infinity or a NaN value), or if any value is negative (less than zero), then abort these steps (without throwing an exception; user agents could show a message on a developer console, though, as that would be helpful for debugging).

I guess maybe you'd want to define a term like "optionally warn in the developer console" which is something like "Optionally, call Printer with "warn" and a List containing an appropriate message string". Maybe also "log an exception in the developer console given a JavaScript object e" which is "call Printer with "error" and a List containing e."

Then all the call sites could cross-link to these terms. It wouldn't be much different than today, but it would kind of emphasize that things all tie together---HTML's "developer console" and the console discussed in the Console Standard.

[Fishrock123]

I should note that true warnings are impossible for Node.js to implement. We only have two channels available, stdout and stderr as dictated by external factors.

Currently warnings in Node.js go to stderr.

[domenic]

Well, I'm not sure "impossible to implement" is quite the right term. You can implement the Printer however you please. E.g. you could prepend the logLevel before writing out the string, or use different colors, or whatever. (Or do nothing different between warn and error.) There's no requirement involving POSIX output streams in the spec.

[Fishrock123]

Right, I meant in the regard to having them be a) just the output that user provided, and b) differentiable.

Perhaps the spec does/will not require those points?

[domenic]

Yeah, if you read the spec I linked to, you can see no such requirements.

[domfarolino]

This seems like a good idea and the more we reference vague hand-wavy warning-reporting things in the standard the more I want to do this. I propose we move forward with this by creating a report a console warning or report a developer console warning that both this specification and others can use. Callers of it can also use it optionally, such as: "optionally, report a developer console warning with the warning 'Blah blah blah'"

It should be an easy enough change that I'm happy to take on. Looks like it'll provide a good ROI when we and other specs want to handle warning-reporting things, especially if you do it a lot (this should keep things DRY).

[annevk]

We should probably leave the actual warning undefined. Instead the algorithm can say that it should be something appropriate and localized for the occasion. And it needs to be optional of course.

[domfarolino]

Indeed, summarizing IRC: Callers can provide something generic (kinda like the warning we provide in time()), but don't have to provide anything. And as you said we should make it clear that:

• The warning is purely advisory
• May be subject to localization (so should probably be general)
• In optional (if none is provided, this standard's algorithm could just display anything that indicates a warning)

[domfarolino]

Ugh, finishing this off soon I promise, got blocked up with a bunch of stuff all at once.

[terinjokes]

@domfarolino How can I help?

[domfarolino]

Will be requesting review soon on a small PR to take care of this, would be great to get feedback; in Seattle this week so things are a tad hectic.