Confusing documentation on I2C configuration

I have seen many examples using the following code to configure the I2C peripheral:
However, the API documentation for the hardware object does not mention a configure() method at all!

Moreover, the API documentation for the I2C object describes how to configure I2C using the method configure() on that object, for example:

Both methods seem to work, so I guess it’s a mix of deprecated legacy code left over from a previous releases, and the preferred way to do it on the current release. Please clarify!

The first one is deprecated; we should tidy up the examples.

Preferred way is the documented one, which passes options in.

I suppose we could really do with an “attic” section, documenting the deprecated methods in case people come across them in older code – theirs as well as ours.


Maybe it’s less work to just include the deprecated methods in the regular API docs, but marked as such. Only if the API does not support the methods anymore, they could go to the attic.

Will the upcoming release 23 drop any classes, methods, constants, or member variables from the current release? Maintaining backward compatibility is a good thing, but it also results in increased code size of the firmware and is hard to maintain properly.

23 doesn’t drop anything, no, just adds a lot of things :slight_smile:

In fact I’m pretty sure we haven’t dropped anything since the very first external release. (And the maintenance burden is largely borne by a good test suite.)