I don't know where else I was supposed to ask this, so I decided to ask here.
There are some grammar and formatting errors in one of the Arduino documentation pages that I would like to fix. However, I can't seem to find a Github repository with the documentation pages in it. If someone could point me to that, I would appreciate it.
Thanks.
Post a link to the page. Please use the chain links icon on the toolbar to make it clickable.
Any efforts to improve the Arduino platform documentation are to be encouraged. I fear, however, that the problems go far deeper than grammar and formatting errors. I don't complain too loudly because I don't want to commit any time and energy to do anything about it and it is, anyway, a problem which is inherent in an Open Software environment where it is difficult to enforce any quality standards unless there are any gifted overlords (Linus Torvalds for example) continuing to maintain strong control.
Anyway, back to the documentation. One illustration of this in the reference:
and is an example of where it would preferable to have nothing.
I agree there are some issues that go deeper than typos but fixing typos is important too. We shouldn't just say "don't bother fixing that spelling error because there are more significant problems on that page". The other problems should be fixed also but maybe I don't have the knowledge for it or the time at the moment. There's a good chance that much of the content will still be valid even when the deeper issues are solved so the minor fixes will still be useful.
You might argue that there are higher priorities for the time of the people who are able to actually make these edits to the website because if they spend all their time handling minor typo fixes they will never get to the more important work. Luckily there is a new system in place that makes it extremely easy for users to propose changes to the Language Reference pages and for the developers to accept those proposals. There is now an "Edit this page" button on every page and when you click that it gets you started on submitting a pull request to that specific Language Reference document in the GitHub repository. It should only take a matter of seconds for a developer to review a simple, obvious fix and click the merge button.
Unfortunately that system is not in place for all the documentation and the previous system is fairly inefficient. Still, I think it's worth reporting issues with those pages even if they end up taking a long time to be dealt with. I was able to quickly go through the issue tracker and close quite a few long-standing reports once the new Language Reference system went into place. They are planning to do the same system for the library reference pages and possibly some of the other documentation content.
6v6gt:
and is an example of where it would preferable to have nothing.
What's wrong with the docs for abs?
Delta_G:
What's wrong with the docs for abs?
Often, when using a function in a strongly typed language like C++, it is useful to have (a) an idea of what datatype(s) the function requires and (b) what datatype it returns. In this case, talking about a "number" is too vague. The user must anyway find a reference manual.
I thought abs was a macro in Arduino land. So it wouldn't know types.
#define abs(x) ((x)>0?(x):-(x))
It would make sense for the reference page to note that abs is a macro. It does provide a hint (though it incorrectly calls it a function at the same time):
Because of the way the abs() function is implemented, avoid using other functions inside the brackets, it may lead to incorrect results.
I suppose the idea is that a beginner will not know or care what a macro is so it's better for them to just think of it as a function but with a warning about the potential pitfall.
OK. Thanks. All is clear now as to why the description appears somewhat vague. So I see the issue as deeper than a documentation issue. It goes back to the design decision to re-implement a standard library function in such a way that it’s behavior is changed subtly and that there is therefore a need to mention it somewhere. Why this has been done would be the topic of another discussion.
If the documentation is intended for “beginners”, I agree that it is probably enough since it is not a c/c++ function but a preprocessor macro, although even beginners have to soon get used to the idea of data types. However, since it is also the only place to warn more experienced users that it, abs() in this case, behaves in a non standard way, then there should be more detail, probably as a footnote stating explicitly that it re-implements the stdlib version and that it is defined in Arduino.h.
But, I suppose that in truth a more experienced user would anyway not look at this documentation and would simply have a nasty surprise if the argument he passes to abs() has certain side effects.
6v6gt:
But, I suppose that in truth a more experienced user would...
#undef abs