Documentation preferences

[SimonMerrett]

Rather than lose @SpenceKonde 's preferences in PR comments, I thought I'd ask for guidance here.

• If we are referring to libraries and header files, there is currently a mix of code and normal text. E.g. flash.h vs flash.h. Any preference?
• Likewise, when referring to a library by its name, not header file, is a syntax preferred to make it clear that we're specifically referring to a library, rather than a physical or logical object, or just capitalisation? E.g. Servo vs Servo vs servo.
• Should text that isn't a function name but would often be written as code have code tags? E.g. INPUT vs INPUT or RISING vs RISING

Will add more as I find inconsistencies.

[SpenceKonde]

I think that if the name of the header is being spelled out including the .h, it should be Library.h (or maybe even <Library.h> - that is most certainly code.

Constants used as arguments to functions and function names should be code as well. I suppose the properties of objects with special purposes (ex, Logic library)

I'm less certain about referring to the name of a library - my instinct says that if there's a library called "EEPROM" which is provided by EEPROM.h and allows access to the eeprom through an object named Flash, then references to the library by name should not be in code tags, but references to the object should be. Ex "EEPROM is the global object provided by the EEPROM library (<EEPROM.h>) to access the on-chip non-volatile EEPROM memory" - Since libraries are so often named after what they interact with, and create an object with the same name, some library readmes and documents would end up full of code blocks to the point of absurdity.

Oh interesting, you can put code tags into headings. That's cool...

code.tag()

blah blah blah

[SimonMerrett]

Cool, fine with all that. I do wonder if it would be a good idea to refer to some terms (e.g. library names) in italics or bold, within the normal flow of text. So we can refer to Tone or Tone using a particular timer. Or, perhaps it should be for peripheral names, so it is clear that we are talking about a peripheral. E.g. AC or CCL or TCA0 and leave it out when talking about analog comparator, logic cells and Type A timer, in general prose.