Documentation fore "return type" of nidigital fetch_capture_waveform method is unclear

[gfisher-NI]

In the documentation for the fetch_capture_waveform method of nidigital, "Return type" is listed as "{ int: memoryview of array.array of unsigned int, int: memoryview of array.array of unsigned int, … }".

This is extremely confusing and gives almost no indication of how to interpret the return type, other than it being a key-value pair.

[gfisher-NI]

As far as I can tell, the only way to convert the return type into something usable is to index it and then convert it to bytes:

capture_samples = digital_session.fetch_capture_waveform('capture_waveform',1)
print(bytes(capture_samples[0]))

[bkeryan]

The text above says

Returns dictionary where each key is a site number and value is a collection of digital states representing capture waveform data

I think that means the return type should be something like dict[int, memoryview[int]] or dict[int, collections.abc.Buffer[int]]. I assume the fact that the memoryview references an array is a hidden implementation detail.

Related: Moving the type documentation out of the docstring and into a type hint would enable validating it at build time. #1887

[gfisher-NI]

@bkeryan The fact that it's an array is one thing that isn't clear, but also, if I just index into the array I get something that looks like:

<memory at 0x000001B8F00A5700>

So there needs to be something about needing to perform some sort of conversion or interpretation.

[bkeryan]

@gfisher-NI Are you indexing a single element or a slice? It seems that slicing a memoryview returns another memoryview that refers to the sliced data: https://docs.python.org/3/library/stdtypes.html#memoryview