What really needs to be done is to create general documentation pages for the Print class functions like what was done for Stream and then link to those pages from the reference pages of every library that inherits from the Print class.
Relevant issue report:
(deleted)
I agree that the documentation can be improved but I think it's quite good already. I don't see any way improved documentation could have helped in this case. The problem was on your end, pure and simple.
If you can point out any specific problems with the documentation or want to suggest any specific improvements, I'll do what I can to get them resolved. The Print class documentation is on my "to do" list, but it's a big project so I haven't gotten to it yet.
huh. Where does the "reference" documentation for libraries live, anyway?
I found Arduino/reference-en for the main references, and I found Arduino-libraries/liquidcrystal for the source code, but I can't find the .adoc files for the the lcd function.
I'll happily cut&paste from the Serial .adocs and submit a pull request for the lcd library (Well, for english, anyway. What a daunting task, to be faced with so many different files to fix in many languages, for each documentation change!)
Unfortunately, there is no repository for the library reference pages and so there is no way to submit pull requests for improvements to them. The accepted method is to submit a pull request. I'm not sure whether Arduino prefers this to be done to the arduino/Arduino repository's issue tracker or the tracker for the specific library (in this case GitHub - arduino-libraries/LiquidCrystal: Liquid Crystal Library for Arduino). I've done both, but have settled on the latter recently since that seems the most appropriate. That said, the issues in arduino/Arduino seem to get more attention from the developers whereas they don't seem to monitor the less actively developed library repositories very closely.
(Well, for english, anyway. What a daunting task, to be faced with so many different files to fix in many languages, for each documentation change!)
We are lucky enough to have a volunteer maintainer for each of the active language reference repository (reference-pt, reference-ko, reference-de, reference-fr) who do a great job of updating their repos to reflect changes to the English language repository. There is a nice system where an issue report is automatically opened in each of the translation repositories whenever there is a commit to the reference-en repo. When it's a change that doesn't require translation, I do like to submit PRs for these after my PR is merged to the reference-en repo, but that's not required and often they will have already made the change to the non-English repos before I get around to doing it myself.
Regarding the situation with the library reference pages: 1.5 years ago, Massimo Banzi made an announcement that they are planning to put the library reference source files in the repositories with the libraries:
https://groups.google.com/a/arduino.cc/d/msg/developers/oyt_c5wePg8/_CWGyAG6CQAJ
Arduino Library format: With the introduction of Arduino 1.6.x we improved the layout of the Arduino libraries to support multiple architectures, metadata and more. One of the areas that needs improvement is documentation. At the moment documentation for libraries is kept separate from the source code itself. We will update the specifications to the Arduino library format to include a folder for documentation that can be written either in markdown or asciidoc. This will allow us to keep the documentation in sync with the code and make sure they don’t go out of sync.
That will be really nice because the current issue report system is extremely inefficient and this will also allow the documentation to be updated in the same commit as changes to the library code that requires a documentation change.
Unfortunately, I have not seen any action on making this happen yet.
data: the data to print (char, byte, int, long, or string)
If you can point out any specific problems with the documentation or want to suggest any specific improvements, I'll do what I can to get them resolved.
lcd.print() has certainly inherited the ability to print a float, and newbie posters are frequently pointed at lcd.print(float, number of places after dp) or told that lcd.print(float) defaults to two places after the decimal point.
cattledog:
lcd.print() has certainly inherited the ability to print a float
Also:
The Serial.print() documentation just says:
Parameters
val: the value to print - any data type
While not actually true, I wonder if that's better than a long list of types?
Anyone have opinions on this?
cattledog:
lcd.print(float, number of places after dp) or told that lcd.print(float) defaults to two places after the decimal point.
That is documented in Serial.print() so westfw's idea of just copy/pasting over that content to the LiquidCrystal reference page would solve the problem.
I'm happy to submit an issue report but I don't want to cross signals with westfw since they already mentioned doing this.
I'm thinking that this bit from the Serial.write() reference would be help in liquidCrystal.write() as well:
Serial.write()
Description
Writes binary data to the serial port. This data is sent as a byte or series of bytes; to send the characters representing the digits of a number use the print() function instead.