Demonstrate return type format in the sample

[per1234]

I notice the formatting of return types documentation is very inconsistent from page to page throughout the documentation. The sample page should establish a formatting standard for return types but currently it only demonstrates how void functions should be documented.

[dkovari]

I agree. In fact it would be extremely helpful if the the documentation also included the argument types. Why not simply include a standard function declaration, for example: ret_type FUNC_NAME(arg_type1 Arg1, arg_type2 Arg2,...)

For functions with multiple argument options and types why not replicate the format used at cppreference.com (see example: http://en.cppreference.com/w/cpp/numeric/math/pow).

[per1234]

@dkovari there's a separate issue for that topic: https://github.com/arduino/reference-en/issues/15

[SeppPenner]

I would like to make a suggestion here, too.

I would organize the whole section from parameters to returns (See image) like the example shown below:

Parameters

Parameter name	Parameter type	Description	Optional
pin	int	The number of the pin on which you want to read the pulse.	[ ]
value	int	type of pulse to read: either HIGH or LOW.	[ ]
timeout	unsigned long	the number of microseconds to wait for the pulse to start; default is one second	[x]

Returns

Return type	Description
unsigned long	the length of the pulse (in microseconds) or 0 if no pulse started before the timeout ()

For the Syntax section I personally would use the suggestion from @dkovari, like

Syntax

pulseIn(int pin, int value)

pulseIn(int pin, int value, unsigned long timeout)

Gist for example is here: https://gist.github.com/SeppPenner/2df12e8f7fb058a3651913839998d468

[SeppPenner]

@per1234 I think, this issue should be closed as the https://github.com/arduino/reference-en/issues/15 discusses it and will provide a soultion to this, too. (Hopefully)

[per1234]

the https://github.com/arduino/reference-en/issues/15 discusses it and will provide a soultion to this, too

Nope. https://github.com/arduino/reference-en/issues/15 is about documenting return types in the reference content. This issue is about documenting how return types should be documented in the reference content.