Question about trait CreateErasedPin being #[doc(hidden)]

[ROMemories]

As part of providing a higher-level abstraction, I'm trying to write a function that would internally instantiate a gpio::AnyInput. However, its constructor requires the passed peripheral to implement CreateErasedPin.
That trait not being part of esp-hal's documentation, as it is marked #[doc(hidden)], I was wondering whether that was only to simplify documentation, or whether that was meant to exclude this trait from the SemVer commitment of esp-hal.

esp-hal/esp-hal/src/gpio/mod.rs

Lines 397 to 400 in 7ea471c

	#[doc(hidden)]
	pub trait CreateErasedPin: Pin {
	fn erased_pin(&self, _: private::Internal) -> ErasedPin;
	}

Is it ok to reference this trait in my function's list of bounds (so I am able to call AnyInput::new() in it), or could this be broken later by a change of esp-hal's API? Or is there a better way of doing this?

[bjoernQ]

We are still refining the API for usability and in general there where and will be breaking changes for now.

The fact the trait is doc-hidden is definitely to make the docs more readable since most users won't care much about those traits. Currently it's not planned to remove that trait but if we consider another solution as a better option, we might change code there. We usually provide migration guides with every release but in this case (since it's doc-hidden) we probably won't.

I don't know enough about your code to suggest alternatives unfortunately - depending on what exactly you are trying to achieve maybe taking AnyInput and let the user create them might be more future proof but as said I really don't know enough about your code.

[ROMemories]

Thank you for you quick reply!

The fact the trait is doc-hidden is definitely to make the docs more readable since most users won't care much about those traits.

This definitely answers my question for now.

This is just to highlight that moving the AnyInput instantiation from the blinky_erased_pins example to its own function (and making the function generic so it can take any input pin), does require accessing the CreateErasedPin trait right now:

esp-hal/examples/src/bin/blinky_erased_pins.rs

Lines 40 to 42 in af1febf

	let button = io.pins.gpio9;
	let button = AnyInput::new(button, Pull::Up);

This would become something along the lines of (contrived example):

fn new_any_input_with_pull_up<P: InputPin + CreateErasedPin>(pin: impl Peripheral<P = P> + 'static) -> AnyInput<'static> {
    AnyInput(pin, Pull::Up)
}

let button = new_any_input_with_pull_up(button);

Closing as this does not require any action for now, thanks for your help!