Arduino Forum

Using Arduino => Project Guidance => Topic started by: tuloski on Oct 23, 2019, 09:22 am

Title: Documentation of print() is not complete
Post by: tuloski on Oct 23, 2019, 09:22 am
The documentation here https://www.arduino.cc/en/Reference/FilePrint is wrong and/or not complete.

The second input is the BASE only if the first input is an integer. If the first input is a float/double, then the second input is the number of decimals to be printed.

I wrote it here, but I'm not sure it's the best place.
Title: Re: Documentation of print() is not complete
Post by: TheMemberFormerlyKnownAsAWOL on Oct 23, 2019, 10:52 am
Quote
An optional second parameter specifies the base (format) to use; permitted values are BIN(binary, or base 2), OCT(octal, or base 8), DEC(decimal, or base 10), HEX(hexadecimal, or base 16). For floating point numbers, this parameter specifies the number of decimal places to use.
Looks pretty complete/correct to me.

Hint: it's the same class
Title: Re: Documentation of print() is not complete
Post by: tuloski on Oct 23, 2019, 11:13 am
Looks pretty complete/correct to me.

Hint: it's the same class
Why do I see a different documentation?

It's:

Quote
BASE (optional): the base in which to print numbers: BIN for binary (base 2), DEC for decimal (base 10), OCT for octal (base 8), HEX for hexadecimal (base 16).
Title: Re: Documentation of print() is not complete
Post by: TheMemberFormerlyKnownAsAWOL on Oct 23, 2019, 11:24 am
Why do I see a different documentation?

It's:

Because you're not looking at Serial.print documentation.
See the hint above.
Title: Re: Documentation of print() is not complete
Post by: tuloski on Oct 23, 2019, 11:33 am
Because you're not looking at Serial.print documentation.
See the hint above.
Why should I look at Serial.print documentation even if it's the same class? Someone reading the documentation I linked will find wrong or incomplete information IMO. Either point to Serial.print documentation or correct it.
Title: Re: Documentation of print() is not complete
Post by: lastchancename on Oct 23, 2019, 11:42 am
I googled 'Arduino serial' and clicked through to 'print'
 https://www.arduino.cc/reference/en/language/functions/communication/serial/print/ (https://www.arduino.cc/reference/en/language/functions/communication/serial/print/)
It worked for me...!
Title: Re: Documentation of print() is not complete
Post by: tuloski on Oct 23, 2019, 11:58 am
I googled 'Arduino serial' and clicked through to 'print'
 https://www.arduino.cc/reference/en/language/functions/communication/serial/print/ (https://www.arduino.cc/reference/en/language/functions/communication/serial/print/)
It worked for me...!
Check on google "SD print arduino".
Title: Re: Documentation of print() is not complete
Post by: lastchancename on Oct 23, 2019, 12:17 pm
aha, you're printing to a file on SD...
Might have helped the initial question.
That can introduce kinks.
Title: Re: Documentation of print() is not complete
Post by: dave-in-nj on Oct 23, 2019, 01:23 pm
aha, you're printing to a file on SD...
Might have helped the initial question.
That can introduce kinks.
his first link was to  FilePrint
his subject line did not specify
but, I think we all know that the Arduino references are not a Master Class, but more of a general overview.
the references only show ways that work and do not begin to try to cover the 1,000 ways it will not work or pointers to watch out for, or tips and tricks on how to do things.
Also, when learning, is it proper to read multiple sources.
In the link for file print, there is no mention of float.
Quote
Parameters
file: an instance of the File class (returned by SD.open() (https://www.arduino.cc/en/Reference/SDopen))
data: the data to print (char, byte, int, long, or string)
as a note, at the bottom, there are instructions
Quote
Corrections, suggestions, and new documentation should be posted to the Forum (http://arduino.cc/forum/index.php/board,23.0.html).
and that takes you to the development forum, not this Project Guidance Forum
....the OP was unsure where to post.

================================
in my view, I think the question is :  
Why, was any note about floats left out in the instructions ?
is there anything special about floats and writing to files ?

Title: Re: Documentation of print() is not complete
Post by: DrDiettrich on Oct 23, 2019, 02:59 pm
AFAIR many commonly used methods are implemented differently in different classes. Unfortunately I found no documentation for the Print base class, the library code should be consulted before changing descriptions, which derived classes implement which variations.
Title: Re: Documentation of print() is not complete
Post by: bperrybap on Oct 23, 2019, 07:17 pm
Why should I look at Serial.print documentation even if it's the same class? Someone reading the documentation I linked will find wrong or incomplete information IMO. Either point to Serial.print documentation or correct it.
You are correct. In more than 10 years I've not seen any Print class documentation. This is broken/wrong and has been this way for MANY (10+) years. Some of the people that have been around Arduino for a long time may know that there is some documentation about the Print class on the Serial page (which was originally about the HardwareSerial class) but that really isn't where it belongs.

It isn't that difficult to fix, as it would simply be moving some stuff around between pages and then creating links to a Print page from any of the pages that used to have their own Print documentation like Serial.


But yeah, its a mess, and should be fixed.

What would probably help is filing an issue on Arduino github page.
I probably should have done this years ago, but have just been too lazy to actually do it.
You could go and create an issue on the Arduino github page, and at least it might have a chance at being addressed/fixed some day.
(github issues is how bugs, issues, and feature requests get addressed)
--- bill
Title: Re: Documentation of print() is not complete
Post by: pert on Oct 23, 2019, 07:42 pm
My idea is that for the shared classes like Print there should be shared reference pages. This way, the documentation for the functions of the classes that inherit from the shared class can only have documentation that are specific to the library and then link to the general shared documentation for the function.

This would reduce the maintenance burden of making fixes or improvements to this documentation. Currently, there are many different versions of documentation of the shared class functions. Some are better than others. It's extremely difficult to get a change pushed through to all the documentation pages.

This was done to some extent with the Stream class:
https://www.arduino.cc/reference/en/language/functions/communication/stream/
we have the shared documentation, but the reference pages of the classes that inherit Stream don't always do a good job of linking to that documentation rather than duplicating the content.

For this idea of creating a shared Print class documentation, the best place to submit an issue report or pull request is here:
https://github.com/arduino/reference-en (https://github.com/arduino/reference-en)

If you instead just want to propose a fix to the SD.print() documentation, I would do that here:
https://github.com/arduino-libraries/sd/ (https://github.com/arduino-libraries/sd/)