pulseIn() documentation is self-contradictory

[ahazybellcord]

As it stands, it's impossible to tell the meaning of the "timeout" parameter used in the pulseIn() function. The documentation states that pulseIn()

Returns the length of the pulse in microseconds or gives up and returns 0 if no complete pulse was received within the timeout.

but later describes the return value as

The length of the pulse (in microseconds) or 0 if no pulse started before the timeout.

The first statement implies that the timeout may occur any time after calling pulseIn(), even while the pulse is "ON" but hasn't yet turned "OFF". The second statement implies that the timeout may only occur before the pulse has started, so that it shouldn't time out once the pulse is "ON". Both cannot be true.

[septillion-git]

See this thread.

According to the C code as comment in wiring_pulse.S of arduino/AVR code (1.8.1) it will timeout if a pulse isn't started and ended between the call to pulseIn() and the timeout.

Aka:

• Pulse not started before timeout = 0
• Pulse not ended before timeout = 0
• Pulse already started when calling pulsIn() (and not followed by a pulse complying with the above) = 0