LiquidCrystal-Lib: Documentation of constructor confusing

[rkost]

https://www.arduino.cc/en/Reference/LiquidCrystalConstructor does not match implementation. Especially explanation of fourbitMode differs (d0 to d3 are used not d4 to d7 according to website).

[agdl]

@rkost can you please point out where D0 to D3 are used?
In the examples and in the description everything use D4 to D7

This is the statement in the page you linked:

d0, d1, d2, d3, d4, d5, d6, d7: the numbers of the Arduino pins that are connected 
to the corresponding data pins on the LCD. 
d0, d1, d2, and d3 are optional; if omitted, the LCD will be controlled 
using only the four data lines (d4, d5, d6, d7). 

[rkost]

Right. This is the statement of the website but if you go into code you will find: https://github.com/arduino/Arduino/blob/master/libraries/LiquidCrystal/src/LiquidCrystal.h#L55
Also in implementation: https://github.com/arduino/Arduino/blob/master/libraries/LiquidCrystal/src/LiquidCrystal.cpp#L44

[bperrybap]

It looks to me like the documentation and the implementation is just fine. The issue is that the library code implementation is sloppy and uses, IMO, stupid names for the pin variables in the 4 bit mode constructor.

It uses the variable names d0,d1,d3,d3 to hold the arduino pin numbers for the lcd signals for d4,d5,d6,d7.

Then, also, based on the code implementation of the loop used, it has to store the pin values for d4,d5,d6,d7 into _data_pins[0] to _data_pins[3] which can also create some confusion for some readers of the code.

i.e. when in 4 bit mode, the library, IMO, uses the stupid names of d0-d3 to hold the arduino pin numbers for the lcd signals for d4-d7 and then stuffs them into _data_pins[0] to _data_pins[3] since the code uses a loop that does either 4 or 8 iterations to set up the pins.

While I personally think there were some dumb choices in variable names and in code implementation, and it can might a bit confusing at first glance without looking at the full implementation, the code, as is, does match the documentation in terms of functionality.

It would be nice if the 4 bit library constructor were fixed to use the variable names d4-d7 instead of d0-d3. I think that would help.

Another thing that would help dramatically would be if the LiqudCrystal example sketches were updated to better indicate the constructor parameters.
IMO this could use improvement:

// initialize the library with the numbers of the interface pins
LiquidCrystal lcd(12, 11, 5, 4, 3, 2);

as it does not clearly indicate what each parameter is.
Yes there are some comments in the sketch above the constructor, that, "if correct", explains things, but It think it could be better.
The naked constructor can cause slightly more technical people to go look at the library code, which then can cause some of those people to get very confused when they see the dumb variable names of d0-d3 being used in the 4 bit constructor.

In the example sketches, I think that this would be better:

// initialize the library with the arduino pin numbers of the LCD interface pins
const int rs=12, en=11, d4=5, d5=4, d6=3, d7=2;
LiquidCrystal lcd(rs,en,d4,d5,d6,d7);

As it indicates the parameters, their order, and that they are arduino pin numbers and not LCD module pin numbers.

[rkost]

Okay, thank you for your explanation @bperrybap ! That was really helpfull. Maybe I will do some refactor of this lib in the future but ATM there is no time for that.

[facchinm]

Fixed by merging arduino-libraries/LiquidCrystal@1d8f63d and updating the docs