vscode-circuitpython

vscode-circuitpython copied to clipboard

Want to get them in the C source in place of the rST? I'm thinking that might be the best way to document going forwards.

Can you elaborate on this? I'm happy to look into it, but I'll need some more info, since I didn't even know what stubs were two weeks ago :D

Totally! We have really good descriptions of our C API in the C source. Here is an example: https://github.com/adafruit/circuitpython/blob/master/shared-bindings/busio/I2C.c#L39

Right now everything with the //| prefix is stripped out into an .rst file. However, we could change that to be a .pyi file and then merge your stubs with our comments. Something like:

//| def readfrom_into(self, 
//|                   address: int,
//|                   buffer: bytearray,
//|                   *,
//|                   start: int = 0,
//|                   end: int = None) -> Any:
//|    """
//|      Read into ``buffer`` from the slave specified by ``address``.
//|      The number of bytes read will be the length of ``buffer``.
//|      At least one byte must be read.
//|
//|      If ``start`` or ``end`` is provided, then the buffer will be sliced
//|      as if ``buffer[start:end]``. This will not cause an allocation like
//|      ``buf[start:end]`` will so it saves memory.
//|
//|      :param int address: 7-bit device address
//|      :param bytearray buffer: buffer to write into
//|      :param int start: Index to start writing at
//|      :param int end: Index to write up to but not include. Defaults to ``len(buffer)``"""
//|   ...

That would allow us to better annotate types and move away from .rst. It'd also allow you to use stubs that are maintained next to the C source.

I've finally gotten to dig into this. The only thing I'm doing to create those stubs is running make VALIDATE= stubs against master of circuitpython if there's been a release since the last release of the vscode extension. Any upstream changes to that make target will get picked up on my end.

any status on this? I recently automated stubgen to recursively run on the .py sources of the library bundle, in an attempt to get some help in vscode.

CircuitPython has switched to pyi in the C source: https://github.com/adafruit/circuitpython/blob/main/shared-bindings/busio/I2C.c#L39 We do need to consistently package them in circuitpython-stubs though.