That is correct. Even though Arduino has recently started moving some of the Arduino library reference content to the public GitHub repositories (example), the Wire library reference content is still hosted in a system that is not open for direct contributions from the community.
It is a bit of a difficult question.
Wire is a "platform bundled library". This means that each Arduino boards platform has its own version of the Wire library (example). This means that the arduino/ArduinoCore-avr repository is not necessarily the most appropriate place to propose improvements to the universally applicable Wire library documentation.
The issue tracker of the arduino/Arduino repository of the classic Arduino IDE has historically served as, in addition to the tracker for issues specific to the code base hosted there, as the "catch all" for issues on subjects that don't have a more specific tracker. So, as far as GitHub goes, that is the best place for proposals that are not specific to one architecture's implementation of Wire. And it is definitely worth a browse through that repository to see the existing discussions:
But recently I have been recommending the use of the contact form because this seems to be slightly more effective at getting action from the people at Arduino who are able to make such changes:
Either way, my experience is that you will get the best results if you provide, in addition to an explanation of why the change is beneficial, the complete suggested text for your proposal so that implementing it can be as much of a copy/paste operation as possible. This saves you from the back and forth after finding that a more vague proposal was not implemented correctly.
And of course you are always welcome to discuss proposals here on the forum. Even though it might not get the notice of those who can implement it, the Arduino community might provide some valuable feedback that will help you to refine your proposal before submitting it to Arduino.
I just found out that the issue is a bit more nuanced than I first thought.
I still think that the documentation should be updated in several places.
Link to Forum is outdated/broken
Incomplete (Timeout functions are not mentioned)
No mention that endTransmission and RequestFrom are blocking
No mention that those functions can block indefinitely (except if you configured a timeout which is not publicly documented (currently timeout is disabled, might change in the future))
At least that's how far I understand the code (which is not very far). So it would for sure be a good thing af anyone could tak a look and correct me if I'm wrong (which is probably the case).
From twi.c
// twi_timeout_us > 0 prevents the code from getting stuck in various while loops here
// if twi_timeout_us == 0 then timeout checking is disabled (the previous Wire lib behavior)
// at some point in the future, the default twi_timeout_us value could become 25000
// and twi_do_reset_on_timeout could become true
// to conform to the SMBus standard
// http://smbus.org/specs/SMBus_3_1_20180319.pdf
static volatile uint32_t twi_timeout_us = 0ul;
static volatile bool twi_timed_out_flag = false; // a timeout has been seen
static volatile bool twi_do_reset_on_timeout = false; // reset the TWI registers on timeout
From wire.cpp
uint8_t TwoWire::requestFrom(uint8_t address, uint8_t quantity, uint32_t iaddress, uint8_t isize, uint8_t sendStop)
{
if (isize > 0) {
// send internal address; this mode allows sending a repeated start to access
// some devices' internal registers. This function is executed by the hardware
// TWI module on other processors (for example Due's TWI_IADR and TWI_MMR registers)
beginTransmission(address);
// the maximum size of internal address is 3 bytes
if (isize > 3){
isize = 3;
}
// write internal register address - most significant byte first
while (isize-- > 0)
write((uint8_t)(iaddress >> (isize*8)));
endTransmission(false);
}
// clamp to buffer length
if(quantity > BUFFER_LENGTH){
quantity = BUFFER_LENGTH;
}
// perform blocking read into buffer
uint8_t read = twi_readFrom(address, rxBuffer, quantity, sendStop);
// set rx buffer iterator vars
rxBufferIndex = 0;
rxBufferLength = read;
return read;
}
From master_reader.ino (in wire examples)
#include <Wire.h>
void setup() {
Wire.begin(); // join I2C bus (address optional for master)
Serial.begin(9600); // start serial for output
}
void loop() {
Wire.requestFrom(8, 6); // request 6 bytes from slave device #8
while (Wire.available()) { // slave may send less than requested
char c = Wire.read(); // receive a byte as character
Serial.print(c); // print the character
}
delay(500);
}
At the current time, the while (Wire.available) is not necessary because Wire.requestFrom() will either block or return all the bytes requested because no timeout is set. And even if it did not return all the bytes, Wire.RequestFrom() has a return value of the number of bytes it got back! So there is no reason for the while but it could be handled in a for loop.