Azure / azure-iot-sdk-c

A C99 SDK for connecting devices to Microsoft Azure IoT services
https://azure.github.io/azure-iot-sdk-c
Other
587 stars 739 forks source link

[Documentation fix] unclear documentation in iothub_client_sample_upload_to_blob_with_retry.c #2638

Open bertulli opened 1 month ago

bertulli commented 1 month ago

SDK Version

I'm on commit 033308b35 , that should refer roughly to Release LTS_03_2024_Ref02

Describe the Bug The sample file iothub_client_sample_upload_to_blob_with_retry.c is still present in the SDK but it is undocumented. It is not advised on the README page of the samples, and it is somewhat similar to iothub_client_sample_upload_to_blob_mb.c, but in the latter there is explicitely a comment describing what the sample does:

// "block_count" is used to simulate reading chunks from a larger data content, like a large file.
// Note that the IoT SDK caller does NOT free(*data), as a typical use case the buffer returned 
// to the IoT layer may be part of a larger buffer that this callback is chunking up for network sends.

while in the former there is no indication. I read the former before, so I got confused and for instance thought the block segmentation was done automatically, thus sending to the cloud ten copies per file. I thought this may happen to other too, so I thought it could beneficial to insert a note in the documentation or the file, or simply deleting it and keeping only the mb one.