Go Down

Topic: WiFi101Client Write() documentation (Read 671 times) previous topic - next topic

noedig

The documentation for the write() function of the WiFi101 Client and Server classes is lacking.
https://www.arduino.cc/en/Reference/WiFi101ClientWrite
https://www.arduino.cc/en/Reference/WiFi101ServerWrite

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!).


PaulS

Quote
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.
The art of getting good answers lies in asking good questions.

noedig

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.

PaulS

Quote
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.

The art of getting good answers lies in asking good questions.

Go Up