Using code_typed to generate docstring templates

If that function is intended to always take a::Int64, then no, but you should restrict the annotation accordingly. If you intend users to be able to provide other types for a, then yes it’s very bad to document only one possible type for it because documentation is for usage.

Some functions are documented with abstract types e.g. AbstractArray, but obviously not every concrete subtype that ever existed can be tested at once. The contract in composability is that the developer has adequately implemented and tested an interface and the users in turn have faithfully extended that interface to new types, therefore new code that developers can’t possibly anticipate will still work. Of course some part of that can go wrong in practice, hence bug reporting and patches.

1 Like