Add subdiagonalCount:superdiagonalCount: argument labels to Tensor.bandPart.

[dan-zheng]

subdiagonalCount:superdiagonalCount: argument labels improve clarity.
Parameter descriptions copied from https://www.tensorflow.org/api_docs/python/tf/linalg/band_part.

cc @awav

[dan-zheng]

swift-models needs to be updated after this patch:

/swift-models/Transformer/Model.swift:95:29: error: missing argument labels 'subdiagonalCount:superdiagonalCount:' in call
    let mask = ones.bandPart(-1, queryTimeSteps - keyTimeSteps)
                            ^
                             subdiagonalCount:  superdiagonalCount:

[saeta]

I'm a big +1 on the improvements to the documentation. Thank you.

As for switching from positional arguments to required argument labels... I think this is a good use, as it is very easy to forget which one is for above the diagonal, and which one is for below. My only concern is that this makes writing out an invocation of bandPart to be very long. I don't have a better idea for now, so this LGTM in general.

One quick nit, however: could you add a deprecated no-label version to help make it a smoother migration for users?

Thanks very much!

[saeta]

One quick nit, however: could you add a deprecated no-label version to help make it a smoother migration for users?

I suspect this will also help get CI to pass (https://source.cloud.google.com/results/invocations/5b144b04-f116-41f9-b435-574cd360de47/targets/s4tf%2Fapis%2Fubuntu%2Fpresubmit/log)

[dan-zheng]

One quick nit, however: could you add a deprecated no-label version to help make it a smoother migration for users?

Sure! Done in 71db9e5.

[awav]

@dan-zheng, Agree. The verbosity is an important thing and it is good to have the naming to avoid confusion. I don't have a strong opinion about how the arguments should be called in bandPart case. Although, I must ask, what do you think about slightly shorter version subdiagCount and superdiagCount?

[dan-zheng]

@dan-zheng, Agree. The verbosity is an important thing and it is good to have the naming to avoid confusion. I don't have a strong opinion about how the arguments should be called in bandPart case.

I'm glad we all agree!

The Swift API design guidelines clearly (haha) advocate clarity:

• Clarity at the point of use is your most important goal. Entities such as methods and properties are declared only once but used repeatedly. Design APIs to make those uses clear and concise. When evaluating a design, reading a declaration is seldom sufficient; always examine a use case to make sure it looks clear in context.

• Clarity is more important than brevity. Although Swift code can be compact, it is a non-goal to enable the smallest possible code with the fewest characters. Brevity in Swift code, where it occurs, is a side-effect of the strong type system and features that naturally reduce boilerplate.

---

Although, I must ask, what do you think about slightly shorter version subdiagCount and superdiagCount?

The Swift API design guidelines recommend avoiding abbrevations:

• Avoid abbreviations. Abbreviations, especially non-standard ones, are effectively terms-of-art, because understanding depends on correctly translating them into their non-abbreviated forms.

The intended meaning for any abbreviation you use should be easily found by a web search.

"Easily found by a web search" is a concrete measure that we can verify:

• https://lmgtfy.com/?q=subdiag
• https://lmgtfy.com/?q=superdiag

The top results for "subdiag" and "superdiag" are not related to diagonals from linear algebra: "diag" refers to something else, as in "subdiagram" or "super diagnostics".

Later results do reference subdiagonals and superdiagonals, showing that "subdiag" and "superdiag" are common in-domain abbreviations. They're very reasonable as local variable names.

To adhere to the API design guidelines and to maintain consistency with the rest of the codebase, I'd recommend that we continue to avoid abbreviations.

[dan-zheng]

Review feedback has been addressed.
Merging to avoid conflicts with pending patch for TF-1076: using @derivative for derivative registration.