search

arduino / reference-en

Editable source for the Arduino Reference
https://www.arduino.cc/reference/en/
Other
163 stars 728 forks source link

Document ternary operator #519

Open per1234 opened 5 years ago

per1234 commented 5 years ago

Migrated from https://github.com/arduino/Arduino/issues/6247

I'm going to leave off the text of the original issue because it was written under the misunderstanding that this is a feature specific to Serial.print(). However, there are some valuable replies in that thread in support of adding this page to the Language Reference and discussing which section it should be placed in.

Related:

per1234 commented 5 years ago

EDIT: see following reply for my updated opinion I have mixed feelings about this proposal. The Arduino Language Reference is not intended to be a complete C++ language reference. It documents the Arduino core library API as well as the basics of the C++ language most likely to be used by a beginner. I don't think the ternary operator is something that a beginner is likely to encounter or have a use for.

There are excellent C++ references already available online for the user who needs more advanced language features.

On the other hand, this is going to impossible to look up in a search engine without knowing the term "ternary".

I see mostly support for this proposal from the community and no "wontfix" decision from Arduino so I think it's worth further consideration. I wouldn't oppose it if the decision is made to move forward.

per1234 commented 5 years ago

In my previous reply, I was operating under the understanding that the .ino files of Arduino sketches were written in C++, and therefore it was reasonable to expect the users to use C++ references in conjunction with the Arduino Language Reference. Since that time, I was informed that .ino files are written in Arduino Language, not C++. The Arduino Language Reference is the sole official and comprehensive documentation of this Arduino Language that exists on the Internet. Thus, any feature of the Arduino Language is a valid and necessary subject for the Arduino Language Reference, including the ternary operator.

animeshsrivastava24 commented 5 years ago

@per1234 I went through the relevant discussions mentioned in the comment section of this issue. I created a draft version of the ternary operator. Here: https://github.com/animeshsrivastava24/Technical_Writing/blob/master/ternary_operator.adoc

I also wanted to suggest that ternary operator should be present under a separate section Ternary Operator since we're having a section named Boolean Operators that represents two arguments based evaluation, so since ternary works on three-argument so it should have a separate section.

Please guide me. Waiting for feedback and review.

per1234 commented 5 years ago

I created a draft version of the ternary operator. Here: https://github.com/animeshsrivastava24/Technical_Writing/blob/master/ternary_operator.adoc

It looks pretty good. I would request that you use the Arduino IDE's Tools > Auto Format (or Ctrl + B in the Arduino Web Editor) to correctly format your example code.

I also wanted to suggest that ternary operator should be present under a separate section Ternary Operator

There is some good discussion about the correct section for this documentation in https://github.com/arduino/Arduino/issues/6247, but unfortunately no consensus. The proposed locations:

I haven't formed an opinion on this, though control structures is appealing to me.

Please guide me.

I think it would be good to have a pull request for this, but I would like to get some input from someone else at Arduino before merging it so it might sit a while or even never get merged.

It's really dependent on the decision regarding https://github.com/arduino/reference-en/issues/623. If we were to decide to go with my first proposal to solve that issue, then it would not be necessary to add documentation for the ternary operator, since the external C++ reference will document it. If we are going with my second proposal for solving that issue, then we absolutely need to add documentation of the ternary operator. The default alternative is to stick with the current approach of not completely documenting the Arduino programming language. In that case, we need to decide on a case by case basis which things should be in the Arduino Language reference.

Unfortunately, I have not gotten any input on that issue yet. If no decision is made, then we stick with the default and I would then likely be in support of adding your page, since this seems to be one of the most popular requests.

animeshsrivastava24 commented 5 years ago

It looks pretty good. I would request that you use the Arduino IDE's Tools > Auto Format (or Ctrl + B in the Arduino Web Editor) to correctly format your example code.

Thanks a lot for the review. Yes, I've modified the example code using the Web Editor. Here is the link to the file:

https://github.com/animeshsrivastava24/Technical_Writing/blob/master/ternary_operator.adoc

It's really dependent on the decision regarding #623. If we were to decide to go with my first proposal to solve that issue, then it would not be necessary to add documentation for the ternary operator, since the external C++ reference will document it. If we are going with my second proposal for solving that issue, then we absolutely need to add documentation of the ternary operator. The default alternative is to stick with the current approach of not completely documenting the Arduino programming language. In that case, we need to decide on a case by case basis which things should be in the Arduino Language reference.

Unfortunately, I have not gotten any input on that issue yet. If no decision is made, then we stick with the default and I would then likely be in support of adding your page since this seems to be one of the most popular requests.

Definitely, I can understand. I'll be eagerly waiting for someone else from Arduino to review and express his/her views on the PR. At present, I have created a file under Control Structure, later on, in case of other opinions I'll be more than happy to shift it.