Go Down

Topic: Documentation of print() is not complete (Read 173 times) previous topic - next topic

tuloski

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.

TheMemberFormerlyKnownAsAWOL

#1
Oct 23, 2019, 10:52 am Last Edit: Oct 23, 2019, 11:01 am by TheMemberFormerlyKnownAsAWOL
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
Please don't PM technical questions - post them on the forum, then everyone benefits/suffers equally

tuloski

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

TheMemberFormerlyKnownAsAWOL

Why do I see a different documentation?

It's:

Because you're not looking at Serial.print documentation.
See the hint above.
Please don't PM technical questions - post them on the forum, then everyone benefits/suffers equally

tuloski

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.

lastchancename

Experienced responders have a nose for laziness, (they were beginners once)... Sure, there are trolls, chest-beaters, and pretenders - but the help you'll get here is about as good as it gets - if you try to help youself!.

tuloski


lastchancename

aha, you're printing to a file on SD...
Might have helped the initial question.
That can introduce kinks.
Experienced responders have a nose for laziness, (they were beginners once)... Sure, there are trolls, chest-beaters, and pretenders - but the help you'll get here is about as good as it gets - if you try to help youself!.

dave-in-nj

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())
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.
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 ?


DrDiettrich

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.

bperrybap

#10
Oct 23, 2019, 07:17 pm Last Edit: Oct 23, 2019, 07:19 pm by bperrybap
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

pert

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

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/

Go Up