Sketch out prose for algorithm definitions. about infra

[tabatkins]

Looking at some of my other algorithms, I do have this pattern which I like a bit better:

The to(unit) method converts an existing CSSNumericValue this into another one with the specified unit, if possible. When called, it must perform the following steps:

Generalized, we get:

The <dfn>foo</dfn> algorithm takes a string |bar| and returns a {{Baz}} or null. When called, it must perform the following steps:

I like this because if your inputs or outputs are complicated enough to be awkward to inline into the first sentence, it's totally natural to just move them to a following sentence:

The <dfn>foo</dfn> algorithm takes a string |bar1|. Optionally, it can take a string |bar2|; if not passed, |bar2| defaults to "bar2". It returns a {{Baz}} or null. When called, it must perform the following steps:

[domenic]

The main problem I have here is the same problem I have with (most) strongly typed languages: verbosity. For example, consider an algorithm from Infra, slightly modified to not mutate its input in-place:

The ASCII lowercase of a string is the result of replacing all ASCII upper alphas in the string with their corresponding code point in ASCII lower alpha.

Even if we go with a sentence-ey version like CSP/ES instead of something more structured, this still ends up as something unwieldy like

To ASCII lowercase a string s, which will return another string, return the result of replacing all ASCII upper alphas in s with their corresponding code point in ASCII lower alpha.

I think we could encourage people to declare inputs in a uniform way, but the outputs should be inferrable from the algorithm itself (like in programing languages that type-infer), and the inputs shouldn't necessarily need to be named if doing so is silly like it is above.

[mikewest]

Like everything, this is a spec, not a cop. :) There will always be trivial things where it doesn't matter whether we specify types and variables and etc. But there will be cases where it does, and cases inbetween.

To pick on Fetch for a moment, look at https://fetch.spec.whatwg.org/#extract-header-list-values, which is not that complicated, but I completely missed that it could "return failure", and only accounted for null and a list of things in my first pass at w3c/webappsec-clear-site-data#17 (comment). It would have been helpful if that was pulled out of the algorithm for people who don't read (like me). :)

To your example, first I'd say that your unwieldy version doesn't sound that bad. Might be a little tighter as "To ASCII lowercase a string |s|, return the string which results from replacing all ASCII upper ... " (which seems like a reasonable one-liner formulation). I'd also note if you change the algorithm to return a new string, then you need to stick a copy operation in there somewhere, so you need to know what to copy, and at that point it might not make sense to make it a one-liner anymore.

It's a judgement call, of course. Simpler algorithms might not need additional context. That seems fine, really.

As an aside, I'd also suggest that the algorithm is actually a bit hand-wavey. What is a "corresponding code point"? What does it mean to "replace all ASCII upper alphas"?

[annevk]

In w3ctag/design-principles#109 @tabatkins argued to some extent for listing the return values of algorithms upfront. It's still a tradeoff, but if this is a thing folks want to do it'd be nice if there was a consistent way of doing it.

(I think I'm somewhat onboard with being able to call out more complicated cases, e.g., when something can return null, failure, or an object.)

[tabatkins]

It's a little verbose and I don't always like it, but [CSS Syntax describes inputs and outputs explicitly]:

This section describes how to consume an ident-like token from a stream of code points. It returns an , , , or .

Or, with an optional argument:

This section describes how to consume a string token from a stream of code points. It returns either a or .

This algorithm may be called with an ending code point, which denotes the code point that ends the string. If an ending code point is not specified, the current input code point is used.

I'm not happiest with the verbose "This section describes how to..." opening, but I haven't come up with a less awkward phrasing that lets me pack the return values into there.

I've mainly just been loathe to say "To foo-alg an input-arg, perform the following steps. This algorithm returns bar1, bar2, or null." because I feel like "following steps" always needs to end in a colon and be the last part of the paragraph. Maybe I'm just being too weird about that, and it's totally fine?

[domenic]

For the original question here, I've come around to thinking we should do something, although perhaps losely. Maybe I'll try to draft something and see what people think?

The harder part is optional and named arguments. I've opened a dedicated issue for that in #320.

[domenic]

I drafted something at #321 if people want to take a look.

[jugglinmike]

We're discussing an algorithm with multiple return values in HTML. In that case, all of the values may not be needed by all of the call sites. Has this come up before? Should the solution here also address if/how callers can succinctly assert that they don't need some output?

[annevk]

@jugglinmike I think in those cases you could also switch to returning a tuple using (value1, value2) and then a caller would use returnValue[0] only or some such. (One thing that might need clarification is that in such cases there's no need for a whole formal tuple setup, imo, as it's clear enough from context what is going on that no type introduction is needed.)