The documentation for the write() function of the WiFi101 Client and Server classes is lacking.
The page only describes the version of the function to write a single byte and not the overloaded function
size_t WiFiClient::write(const uint8_t *buf, size_t size)
The documentation for the UDP class write function covers both cases. However, wouldn't it be more useful to specify that the buffer argument needs to be a pointer? It's probably obvious to a programmer but possibly not for someone inexperienced (for whom Arduino is meant!).
However, wouldn't it be more useful to specify that the buffer argument needs to be a pointer?
What else would it be? Arrays (the only other logical choice) are just pointers to the first element.
That's true, but why make the documentation vague when it can be precise?
Anyway, it probably doesn't really matter. The bigger issue is the lacking documentation of the first two mentioned functions.
That’s true, but why make the documentation vague when it can be precise?
Nobody likes doing documentation. Those who know enough to write the documentation can have a hard time understanding why others don’t have the same knowledge. If you do have that knowledge, you don’t need the documentation.
What is really needed is a peer-review of the documentation. Whoever is writing it needs a teddy-bear. The documentation should be written as though you are describing a complex topic to a teddy-bear. Then, someone else, who is not an expert, should review the material before it is posted.
The problem is that no one wants to perform either role, or set up the team structure to enforce that the process is followed.
To add to the complexity, Client and Server are derived classes, so the write() method really belongs to the base class. It should not be documented again and again for each class that derives from the base class (or some class that derives from the base class), except to explain how the derived class specifically uses the method.