[*.py] Standardise docstring usage of "Default to"

[SamuelMarks]

It's me again! - PS: I can split this into multiple PRs if you prefer.

---

I am trying to treat JAX, TensorFlow, PyTorch and Keras [amongst others] as data.

For example, translating the API hierarchy from Python to SQL; or generating type-safe help-text included CLIs. This will enable a number of new use-cases.

Unfortunately as it stands, your codebase lacks the type specificity for these use-cases. This is the first, probably of many, PRs to make your codebase consistent enough to be useful for these cases.

Additionally it'll generate better documentation for your primary use-cases; and make it clearer what types are being used where.

E.g., Defaults to 1. is ambiguous. Is 1 a float or an int?

Knowing the difference is then useful for continuous variable optimisation (e.g., Ray Tune or Google Vizier hyperparameter optimisation across the int or float domain). (as an aside; I am interesting in constraining the type numerical range more specifically also; like ASN.1 or Fortran allows)

[fchollet]

Looks good, thank you! Question: how do we prevent future drift? Do you have a docstring linter we could run on CI?

[SamuelMarks]

@fchollet You're welcome.

As for a linter, I'd have to investigate the options and maybe extend them with defaults to linting:

• https://github.com/jsh9/pydoclint
• https://github.com/pycqa/pydocstyle
• https://github.com/akaihola/darglint2

Will see if I can send you a PR for it soon.

I think in the meantime having this consistency throughout the codebase gives new contributors a hint as to the expectation.

[fchollet]

Sure, thanks for investigating. I just assumed that you must have used some automation to create the PR, so perhaps this could be the basis for a very basic linter.

LGTM -- merging the PR now!