Documentation for machine.Pin Class

[osamarais]

The documentation at
https://docs.micropython.org/en/latest/ ... e.Pin.html

shows the constructor to be of the form:
class machine.Pin(id, mode=-1, pull=-1, *, value, drive, alt)

However, value, drive, and alt are not supported by the ESP8266. Passing these arguments gives the extra positional arguments error.
Is this there for compatibility across different devices? If so then I guess it shouldn't give an error; just ignore the extra arguments (maybe tell that the object was created but the extra arguments were ignored).

Any ideas?

[jickster]

The documentation at
https://docs.micropython.org/en/latest/ ... e.Pin.html

shows the constructor to be of the form:
class machine.Pin(id, mode=-1, pull=-1, *, value, drive, alt)

However, value, drive, and alt are not supported by the ESP8266. Passing these arguments gives the extra positional arguments error.
Is this there for compatibility across different devices? If so then I guess it shouldn't give an error; just ignore the extra arguments (maybe tell that the object was created but the extra arguments were ignored).

Any ideas?

Yes: the documentation is not maintained; look at the C-code.

Code: Select all

 STATIC mp_obj_t pyb_pin_obj_init_helper(pyb_pin_obj_t *self, size_t n_args, const mp_obj_t *pos_args, mp_map_t *kw_args) {
    enum { ARG_mode, ARG_pull, ARG_value };
    static const mp_arg_t allowed_args[] = {
        { MP_QSTR_mode, MP_ARG_REQUIRED | MP_ARG_INT },
        { MP_QSTR_pull, MP_ARG_OBJ, {.u_obj = mp_const_none}},
        { MP_QSTR_value, MP_ARG_KW_ONLY | MP_ARG_OBJ, {.u_obj = MP_OBJ_NULL}},
    };

As you noticed, there are only 3 arguments allowed.

I’m not a uPy code contributor but I’ve posted requesting documentation and it’s clear it’s not gonna happen; there’s just too much other work to do that’s much higher priority.


Sent from my iPhone using Tapatalk

[mattyt]

I can see that the ESP8266 documentation links to the common docs for machine.Pin. Instead, a new machine.Pin doc file, specific to the ESP8266, needs to be created.

I have a longer-term goal to create ESP32 documentation, I'll try to update the ESP8266 at the same time.

@jickster please don't give up on reporting documentation issues! Although documentation updates have been slow it really does help to have a clear list of the issues that need resolution. If you or @osamarais find any other inconsistencies please note them in this forum or, even better, create a ticket so they can be tracked.

[jickster]

I can see that the ESP8266 documentation links to the common docs for machine.Pin. Instead, a new machine.Pin doc file, specific to the ESP8266, needs to be created.

I have a longer-term goal to create ESP32 documentation, I'll try to update the ESP8266 at the same time.

@jickster please don't give up on reporting documentation issues! Although documentation updates have been slow it really does help to have a clear list of the issues that need resolution. If you or @osamarais find any other inconsistencies please note them in this forum or, even better, create a ticket so they can be tracked.

I've made my peace with it. Anyway I develop at the C-level 99% of time.

[cefn]

@mattyt if you can guide me towards the right resources I'd be happy to help with improving ESP8266 Micropython documentation. Don't know if there's a natural way to form a team around this effort. Thoughts?

I routinely come across missing things and would like to have a place to record that and a pipeline for me and others to fix them but have avoided filing bugs given everyone's workload. Is there such a place already (e.g. a documentation category on the Github Issue tracker )?