Update random.adoc to include PROTOTYPE section #472
Conversation
When I look up a function, often what I'm looking for is data type(s) -- mostly function parameter data type(s) and the return value data type. I like to have that information prominent, so I don't have to dig through the document to find it. And, yes, the Arduino Reference does have a consistent location for this information, but, I'm an infrequent user who codes in several languages [PHP, C/C++, JavaScript, and I'm learning Python]. There's a de facto-ish standard for presenting data type information: near the top, in its own category, formatted as the syntax for the function call with parameter and return value data type indicated. Being an infrequent visitor to the Arduino Function Reference, I tend to forget this non-typical arrangement and wind up having to dig. For the function "delay()", for example, it's a short excursion, but in the case of "random()", this information is buried way down in the "Notes and Warnings" section! My edit puts typing information at the top, in its own category, making this information easy to acquire. BTW: I'm betting this was omitted to keep this document Noob-friendly, so I'm sympathetic to this possible concern. But, adding this would be an asset for coders like me. Examples of the defacto-ish formatting I'm referring to: > https://en.cppreference.com/w/c/numeric/math/abs > http://us3.php.net/manual/en/function.strstr.php
|
Hi Steve Thanks for the pull request, however, it introduces a new section on the file, which if accepted would then be needed for every each file in the reference. Big changes like this are discussed on issues before action. That said, the PR can not be accepted. However, I do recognize that the page is missing information. There is some inconsistency, but the preferred layout for the parameter and return sections seems to be the variables, followed by meaning and type.
So as you mentioned, the page you for random() has been missing the data types in the 'Parameters' section. If you are keen, you can edit your PR do fix just that, without the new section. For discussing the change you mentioned, you can visit issues #15 and #199. Thanks again. |
When I look up a function, often what I'm looking for is data type(s) -- mostly function parameter data type(s) and the return value data type. I like to have that information prominent, so I don't have to dig through the document to find it. And, yes, the Arduino Reference does have a consistent location for this information, but, I'm an infrequent user who codes in several languages [PHP, C/C++, JavaScript, and I'm learning Python]. There's a de facto-ish standard for presenting data type information: near the top, in its own category, formatted as the syntax for the function call with parameter and return value data type indicated. The Arduino Function Reference documents do not follow this standard, and being an infrequent visitor to the Arduino Function Reference, I tend to forget this atypical arrangement and wind up having to dig for it.
In the case of the "delay()" function, it's a short excursion, but in this document, typing information for the "random()" function's parameters, is buried way down in the "Notes and Warnings" section!
My edit puts typing information at the top, in its own category, making this information easy to acquire.
BTW: I'm betting this was omitted to keep this document Noob-friendly, so I'm sympathetic to this possible concern. But, adding this would be an asset for coders like me.
Examples of the defacto-ish formatting I'm referring to: