Use standard format for Syntax, Parameters, and Returns sections #559

per1234 · 2019-02-21T12:51:10Z

I have faithfully followed the standard established by the reference sample. The exception is in documenting the return type, since the reference sample does not provide any guidance on this subject. In this, I attempted to be consistent with the standard established for documenting parameter types ("Allowed data types:" for parameters, "Data type:" for return type).

Note that this PR only reformats the existing content regarding parameter and return types. Documenting all parameter and return types will be done in a separate PR.

Fixes #559

SeppPenner · 2019-04-26T06:09:23Z

@robsoncouto Can you merge this, please? This would be a huge step towards consistency.

robsoncouto · 2019-04-26T17:27:02Z

Hi @SeppPenner. I'm favor of consistency. However, as this pull request changes so many reference files, I would prefer that someone from the Arduino team could review and accept it.

SeppPenner · 2019-04-28T11:05:26Z

@robsoncouto Ah okay. This might take some time, I guess...

robsoncouto · 2019-05-01T15:35:17Z

@SeppPenner, that is not the problem at all. Besides, per's contributions are generally well organized and a breeze to review. I just feel that this is an important step for the reference, heavily impacting all the other reference repos, and I do not have the authority for accepting it, even though I agree with the change. I believe this is per's opinion as well, please see #536.

SeppPenner · 2019-05-03T06:40:59Z

@robsoncouto I know, I have already talked to him somewhere else about this^^

I have faithfully followed the standard established by the reference sample. The exception is in documenting the return type, since the reference sample does not provide any guidance on this subject. In this, I attempted to be consistent with the standard established for documenting parameter types ("Allowed data types:" for parameters, "Data type:" for return type).

per1234 · 2019-05-03T08:29:10Z

I believe this is per's opinion as well, please see #536.

It's actually not my opinion. #536 is different from this PR in that it is changing the official policy, whereas this PR is only enforcing the existing official policy.

There are two exceptions:

Return type: Despite my request in Demonstrate return type format in the sample #199 1.5 years ago, no official guidance has been given for how to document return types. However, my changes don't violate the policy (since it's silent on this topic) and attempt to be consistent with the other formatting.
Code markup on type names: I notice now that the sample reference page does not use code markup on the parameter types, while I have in this PR. Perhaps it would be better for me to update this PR to follow the sample faithfully and remove the code markup from every return type in the reference. I hate to do that, since I prefer that the code markup be used and this seems like a step in the wrong direction, but if it makes the difference for this getting merged I'll do it.

I would prefer that someone from the Arduino team could review and accept it.

Just to be clear, I am a member of the Arduino team since this January. There's no indication of how long we might need to wait for someone else from Arduino to help out with this project.

I'm a bit sad about this because I feel that the Language Reference is starting to get pretty polished but there are a couple more major projects that I was excited and motivated to do.

The first is to specify parameter and return types for all functions (#15) (which is currently done only sporadically), and confirm that all existing type documentation is correct (it's not). This PR lays the groundwork for that project.

The second is to review all the reference pages and correct all the typos I find. I already have a long list of typos I've run across during my work, but I want to fix them all comprehensively, rather than submitting a zillion individual PRs.

These wide-ranging PRs that don't get merged are a burden on me because they get merge conflicts every time a minor PR is merged, and I must constantly be fixing these merge conflicts to keep the PR in a condition where it could be merged if that day ever comes. I feel that the lack of assistance from the Arduino team is an indication they don't feel this work is a high priority. Due to these factors, I've put any further major work on the Language Reference on hold until such time as the situation changes, even though I would very much like to continue with the project.

robsoncouto · 2019-05-03T13:41:28Z

It's actually not my opinion.

I'm sorry, I got that wrong then.

Just to be clear, I am a member of the Arduino team since this January.

When I asked you about this, you simply said that you were given write access to this repository. So I could not know, as I have access and I am not a member :)

Anyways, thanks for your thoughts @SeppPenner and @per1234. Now that I know that per is a member of Arduino and responsible for this repository I don't see reason for holding this any longer. I will check everything and accept this as soon as possible.

per1234 · 2019-05-03T16:13:58Z

So I could not know, as I have access and I am not a member :)

Sorry I didn't made my status more clear before now. I haven't felt like things are so much different now from my years of volunteer status, other than that I have a little more access and more time to dedicate to the project. I'm not yet used to being somewhat "official", whatever that means.

I will check everything and accept this as soon as possible.

Thanks! Let me know if there's anything you want me to change, including the situation with the backticks on the type names. Also, I want to be clear that, although I very much want to see this be merged, I don't hold you to any obligation or expectation to work on this if you don't have the time or desire. I'm forever grateful for all the excellent work you've done so far on the Language Reference project and whatever whatever further work you might have time and energy for.

robsoncouto · 2019-05-10T14:52:42Z

Language/Functions/Communication/Serial/find.adoc


 [float]
 === Returns
-`bool`
+Data type: `bool`.


Do you think this could be replaced with:

true if the target string was found, false otherwise. Data type: bool.

robsoncouto · 2019-05-10T14:54:53Z

Language/Functions/Characters/isAlpha.adoc


 [float]
 === Parameters
-`thisChar`: variable. *Allowed data types:* char
+`thisChar`: variable. Allowed data types: `char`.


Could this be improved as:

thisChar: the character variable. Allowed data types: char. ?

What do you think? Too verbose?

robsoncouto · 2019-05-10T14:56:12Z

Language/Functions/Communication/Serial/findUntil.adoc


 [float]
 === Returns
-`bool`
+Data type: `bool`.


Same as the previous.

robsoncouto · 2019-05-10T15:00:49Z

Language/Functions/Communication/Serial/parseFloat.adoc

 [float]
 === Returns
-`float`
+Data type: `float`.


This one is missing the function's return explanation.

robsoncouto · 2019-05-10T15:03:56Z

Language/Functions/Communication/Serial/print.adoc


 [float]
 === Returns
-`size_t`: `print()` returns the number of bytes written, though reading that number is optional.
+`print()` returns the number of bytes written, though reading that number is optional. Data type: `size_t`.


I think that "print() returns" could be removed here to make things uniform.

robsoncouto · 2019-05-16T19:17:00Z

Language/Functions/Random Numbers/random.adoc

@@ -29,13 +29,13 @@ The random function generates pseudo-random numbers.

 [float]
 === Parameters
-`min` - lower bound of the random value, inclusive (optional)
+`min`: lower bound of the random value, inclusive (optional). +


Missing data types?

robsoncouto · 2019-05-16T19:23:57Z

Language/Structure/Arithmetic Operators/division.adoc

-`numerator` : variable or constant. *Allowed data types:* int, float, double, byte, short, long  +
-`denominator` : *non zero* variable or constant. *Allowed data types:* int, float, double, byte, short, long
-[%hardbreaks]
+`result`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. +


Same as the previous.

robsoncouto · 2019-05-16T19:24:08Z

Language/Structure/Arithmetic Operators/multiplication.adoc

-`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long  +
-`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long
-[%hardbreaks]
+`product`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. +


Same as the previous.

robsoncouto · 2019-05-16T19:24:29Z

Language/Structure/Arithmetic Operators/subtraction.adoc

-`operand1` : variable or constant. *Allowed data types:* int, float, double, byte, short, long +
-`operand2` : variable or constant. *Allowed data types:* int, float, double, byte, short, long
-[%hardbreaks]
+`difference`: variable. Allowed data types: `int`, `float`, `double`, `byte`, `short`, `long`. +


Same as the previous.

robsoncouto · 2019-05-17T05:00:28Z

Language/Variables/Data Types/String/Functions/startsWith.adoc

 [float]
 === Parameters
-`myString, myString2`: a variable of type String
+`myString, myString2`: a variable of type `String`.


myString, myString2: variables of type String.
or could be separated like you did above.

robsoncouto · 2019-05-17T05:19:35Z

Hi @per1234.
While reading the changes, I noticed some inconsistency, but not really related to this PR, so I added some notes. I will merge the pull request already, as I think that if necessary, these can would be better as separate pull requests.
Thanks and sorry for the delay.

per1234 · 2019-05-17T05:53:22Z

Thanks for all the great suggestions @robsoncouto! I agree with all of them and also that they are better for a separate PR. My goal with standardizing the format of these sections was to create a consistent framework to make it easier to implement just these sorts of changes.

per1234 mentioned this pull request Apr 1, 2019

abs() does not work on floats #362

Open

per1234 mentioned this pull request Apr 18, 2019

Fix code highlighting in streamReadBytesUntil.adoc and streamReadBytes.adoc. #581

Closed

SeppPenner mentioned this pull request Apr 18, 2019

Wrong code highlighting in streamReadBytesUntil.adoc. #580

Closed

per1234 mentioned this pull request May 3, 2019

Wrong formatted syntax in all string functions arduino/reference-de#270

Closed

robsoncouto approved these changes May 17, 2019

View reviewed changes

robsoncouto merged commit 7a4fa14 into arduino:master May 17, 2019

per1234 deleted the standard-syntax-parameters-returns-formatting branch May 17, 2019 05:53

Dygear mentioned this pull request May 30, 2019

Specify data types in function definitions #15

Open

per1234 mentioned this pull request Jun 3, 2019

[Documentation] Improve Documentation by Fixing Typos and Documentation Syntax #612

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Use standard format for Syntax, Parameters, and Returns sections #559

Use standard format for Syntax, Parameters, and Returns sections #559

per1234 commented Feb 21, 2019 •

edited

Loading

SeppPenner commented Apr 26, 2019

robsoncouto commented Apr 26, 2019

SeppPenner commented Apr 28, 2019

robsoncouto commented May 1, 2019

SeppPenner commented May 3, 2019

per1234 commented May 3, 2019

robsoncouto commented May 3, 2019

per1234 commented May 3, 2019

robsoncouto May 10, 2019

robsoncouto May 10, 2019

robsoncouto May 10, 2019

robsoncouto May 10, 2019

robsoncouto May 10, 2019

robsoncouto May 16, 2019

robsoncouto May 16, 2019

robsoncouto May 16, 2019

robsoncouto May 16, 2019

robsoncouto May 17, 2019

robsoncouto commented May 17, 2019

per1234 commented May 17, 2019

Use standard format for Syntax, Parameters, and Returns sections #559

Use standard format for Syntax, Parameters, and Returns sections #559

Conversation

per1234 commented Feb 21, 2019 • edited Loading

SeppPenner commented Apr 26, 2019

robsoncouto commented Apr 26, 2019

SeppPenner commented Apr 28, 2019

robsoncouto commented May 1, 2019

SeppPenner commented May 3, 2019

per1234 commented May 3, 2019

robsoncouto commented May 3, 2019

per1234 commented May 3, 2019

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

robsoncouto commented May 17, 2019

per1234 commented May 17, 2019

per1234 commented Feb 21, 2019 •

edited

Loading