Should firmware headings follow syntax? about docs HOT 8 CLOSED

Front-end folks should make the design call whether to stick with all caps headings or not. @jme783 @jenesaisdiq

Either way, we need to always include a code syntax example to show the capitalization. Thank you @kennethlimcp for adding the code block of syntax examples for these two.

from docs.

IMHO headings should NOT be all caps and should, instead, reflect valid syntax.

from docs.

I will say I was bitten by this recently when copy pasting in some func from the docs

Sent from my iPhone

On Jun 16, 2015, at 5:58 AM, Geoff Marshall [email protected] wrote:

IMHO headings should NOT be all caps and should, instead, reflect valid syntax.

—
Reply to this email directly or view it on GitHub.

from docs.

What's the current state of this? Looks to me like docs now have camelCase examples, and that the compile service, at least, is agreeing that camelCase is the correct format (and that ALLCAPS is not).

What'd ya get bitten by, @dmiddlecamp?

from docs.

Center column @jenesaisdiq headings are all caps... I agree these should be proper syntax, or if not... do not show the heading as code syntax. For example: WiFi.clearCredentials() is better than WI-FI CLEAR CREDENTIALS is better than WIFI.CLEARCREDENTIALS()

from docs.

Also, if method returns non-void, strive to provide pseudo-code in the RHS
to indicate useful interpretation of return code.

On Tue, Jun 16, 2015 at 10:18 PM, Technobly [email protected]
wrote:

[image: screen shot 2015-06-16 at 10 11 17 pm]
https://cloud.githubusercontent.com/assets/2249224/8199040/b56496c6-1474-11e5-8a97-a85840216b79.png
Center column @jenesaisdiq https://github.com/jenesaisdiq headings are
all caps... I agree these should be proper syntax, or if not... do not show
the heading as code syntax. For example: WiFi.clearCredentials() is better
than WI-FI CLEAR CREDENTIALS is better than WIFI.CLEARCREDENTIALS()

—
Reply to this email directly or view it on GitHub
#41 (comment).

Andy

from docs.

Ahh, starin' me in the face, thanks @technobly. Will make sure it gets addressed.

Good point @andyw-lala; clearCredentials doesn't especially seem like it needs to have that response caught (for it to be useful), but hasCredentials probably does. I'm not seeing compile errors when I don't assign that return to anything, so it seems that a practical example's the necessary bit.

from docs.

C doesn't complain if you ignore return values, but from a documentation
standpoint, if the function returns useful values, and the descriptive text
explains them, then the example should match.

On Tue, Jun 16, 2015 at 10:38 PM, Richard Whitney [email protected]
wrote:

Ahh, starin' me in the face, thanks @technobly
https://github.com/technobly. Will make sure it gets addressed.

Good point @andyw-lala https://github.com/andyw-lala; clearCredentials
doesn't especially seem like it needs to have that response caught (for it
to be useful), but hasCredentials probably does. I'm not seeing compile
errors when I don't assign that return to anything, so it seems that a
practical example's the necessary bit.

—
Reply to this email directly or view it on GitHub
#41 (comment).

Andy

from docs.