README: Minor readability improvments

[noahwilliamsson]

More consistent formatting and a few fixed typos.

[igrr]

Hi, thanks for the improvements. I'm going to merge everything except "Consistently indicate functions with parentheses" because while some functions really take zero arguments (like millis() and micros()), others need arguments (like pinMode and attachInterrupt), and introducing them without arguments (or some placeholders) is simply not valid. I think the way to go is to make these functions work like hyperlinks pointing to detailed documentation.

[noahwilliamsson]

Hi, thanks for the feedback.

If you're not merging af1b15b you can also skip the dependent commit 68ba4c3.

I agree it would be better show their arguments and also hyperlink them.

If I was to hyperlink the first mention of each function, would it be OK to link to the Arduino reference and use Arduino's syntax style (i.e. leaving out the parameters' data types) where possible? For instance, like this for the Basic Wiring Functions block:
" pinMode(pin, mode), digitalRead(pin), digitalWrite(pin, mode), analogRead(pin) and analogWrite(pin, value) work as usual."

(For the board specific methods (Serial.swap(), Serial.setDebugOutput(), ESP.restart(), etc) I guess README.md will have to do as the authoritative source as there doesn't seem to be any other place where those methods are documented.)

[igrr]

Yes, i think keeping the Arduino syntax style and linking to Arduino reference is fine.
I have cherry-picked your commits on to the doc-update branch:
https://github.com/esp8266/Arduino/tree/doc-update
I've started cleaning up and separating the documentation, the goal is to provide "snapshots" for each core version. Right now everyone looks at the most recent version and this leads to some confusion.

[igrr]

These commits are now part of #587, closing this one.