Go Down

Topic: liquid crystal library is rubbish (Read 1 time) previous topic - next topic

AWOL

#15
Nov 24, 2018, 10:16 pm Last Edit: Nov 24, 2018, 10:17 pm by AWOL
So the liquid crystal library. .
In my mind, the squealing of car tyres and tortured brake discs.

Which "liquid crystal library"?

Quote
Firstly I see no clear distinction between write and print but never mind.
Well, nevermind.

AWOL

#16
Nov 24, 2018, 10:25 pm Last Edit: Nov 24, 2018, 10:32 pm by AWOL
So the hypothetical child or artist needs to be fluent in "C"? OK fair enough.
No,  C++.
But not fluent, just acquainted.
Like you are with English

westfw

Hmm.   I agree that the LCD.print/write documentation is painfully brief.  It should look more like the Serial documentation, or at least refer to that, for a better description of what formatting is supported.
(I think it assumes that people will already be familiar with Serial.xxx() usage, which it "inherits" in the best C++ traditions.

DKWatson

So the hypothetical child or artist needs to be fluent in "C"? OK fair enough.
Usually being not an idiot is sufficient.
Live as if you were to die tomorrow. Learn as if you were to live forever. - Mahatma Gandhi

SparkyLabs

ooh, ooh, OK. If you say so..... I'm obviously an idiot that should stick to writing his own libraries...

pert

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:
https://github.com/arduino/Arduino/issues/2581

spycatcher2k

Quote
ooh, ooh, OK. If you say so..... I'm obviously an idiot that should stick to writing his own libraries...
Well you said it now, so we can now quote it . . . . Idiot!

Don't take things so seriously, Weird how few people complain about that page (Only the one self confessed idiot) , including beginners who have no programming background.
Mrs Drew
-=-
http://www.uk-pcb.co.uk - UK PCB Fab Company
I will design & code for you, but I will also charge you (PM me)
If you don't like my answers, realize : I'm not being cheeky, I'm Just trying to prompt you to use your own brain/google etc.

pert

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.

westfw

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

pert

#24
Nov 25, 2018, 01:02 am Last Edit: Nov 25, 2018, 01:10 am by pert Reason: reference-en link
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 https://github.com/arduino-libraries/LiquidCrystal). 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.

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

pert

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

cattledog

Quote
data: the data to print (char, byte, int, long, or string)
Quote
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.


pert

lcd.print() has certainly inherited the ability to print a float
Also:
  • __FlashStringHelper (though it might be best to let "string" cover that?)
  • String
  • unsigned char
  • unsigned int
  • unsigned long
  • double (actually this is used instead of float in Arduino AVR Boards, I didn't look at the otehr cores)
  • Printable (maybe best to say IPAddress instead, since that's the only use of Printable I know of?)


The Serial.print() documentation just says:
Quote
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?

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.

westfw

I'm thinking that this bit from the Serial.write() reference would be help in liquidCrystal.write() as well:


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

Go Up