image icon indicating copy to clipboard operation
image copied to clipboard

Deprecate compound input fn in favor of Reader

Open HeroicKatora opened this issue 3 years ago • 5 comments

Any comments on the questions below are welcome.

In light of #1318 and previously #1291 , #1232 , #1231 , #1072 , #792 (possibly more), I conclude that opening files with the functions in the main module is at least misunderstood but quite possibly a bad interface in itself. It's often not clear how to do combine aspects of these methods by performing parts of them manually—such as how to open a file with a known image type. In that sense these functions are too numerable and too specific at the same time.

io::Reader intends to fix this by encapsulating the known inputs as an object and then presenting builder-style methods for adjusting the details, independent of whether one opens a file or reads a slice of data from memory.

This PR intends to deprecate the utility wrappers in dynimage, not the primitive methods in io/free_functions.rsguess_format and load. This was always planned.

The main concern is to find the sweet spot for the scope of the deprecation.

  • Are we okay with the set of methods being deprecated?
  • Are the replacements actually easy enough to be discovered? Should we add some more documentation concerning this? One particular sore spot might be loading from memory since no method in Reader takes a byte slice as input. For new Rusteceans the generics might be unecessarily confusing.
  • Should we delay this until a writer has been added?

HeroicKatora avatar Oct 05 '20 20:10 HeroicKatora