Editorial: Make "generically emulated" text a macro, update wording #638
Conversation
Many complex operations in the spec are given decompositions, showing how the operation could be replaced through the use of more primitive operations. This text is repeated in many places. Improve this in two ways: * Use Bikeshed's Text Macro[1] to reduce the repetition. * Streamline the text, and make it explicit that if the underlying platform doesn't support an operation, WebNN API implementations can use the decomposition as a guide to emulate it. The macro [EMULATED] is used at the end of an intro sentence since there are variations - some of the decompositions are grouped, and some make assumptions (e.g. activation functions, layouts, etc). If we assume that implementations must implement all operations in the spec, either via the underlying platform or emulation, this fixes webmachinelearning#187 [1] https://speced.github.io/bikeshed/#metadata-text-macro
There was a problem hiding this comment.
I note we have one outlier case in https://www.w3.org/TR/webnn/#api-mlgraphbuilder-reshape-method where a similar (but not the same) note is added for squeeze, unsqueeze, and flatten ops that are not part of the API:
Many shape-related operations such as squeeze, unsqueeze, and flatten can be generically implemented using the reshape() operation as follows:
Quickly glimpsing over the spec a reader might think those three ops are also part of the API. There's a subtle difference in the wording: "generically implemented" vs. "generically emulated". This is probably intentional but could mislead readers until they click the links and land on PyTorch API docs.
Noting this here because it caught my eye while reviewing. The PR is good as is. My comment can be addressed here or separately as deemed appropriate.
#598 should make that clearer; wording can also be tweaked. |
|
@fdwr , do you have any further comments? |
Many complex operations in the spec are given decompositions, showing how the operation could be replaced through the use of more primitive operations. This text is repeated in many places. Improve this in two ways:
Use Bikeshed's Text Macro[1] to reduce the repetition.
Streamline the text, and make it explicit that if the underlying platform doesn't support an operation, WebNN API implementations can use the decomposition as a guide to emulate it.
The macro [EMULATED] is used at the end of an intro sentence since there are variations - some of the decompositions are grouped, and some make assumptions (e.g. activation functions, layouts, etc).
If we assume that implementations must implement all operations in the spec, either via the underlying platform or emulation, this fixes #187
[1] https://speced.github.io/bikeshed/#metadata-text-macro
Preview | Diff