Make pulse_meter PULSE filter report the pulse as soon as it can

[TrentHouliston]

What does this implement/fix?

See #5813 (comment)

The pulse meter filter would only publish the pulses when the next pulse came through when in PULSE mode.
This caused some strange behaviour when the pulses were slow as features like timeout would happen at unexpected times as even though a pulse had happened since the next pulse hadn't yet it was not counted.

This change allows the main loop to "peek" the filter state to see if it can count the incomplete pulse and repay that pulse count later when the interrupt catches up.

This also resulted in some refactoring to the pulse filter to enable this which simplified it significantly in the process.
I've also added a markdown file to help describe the pulse filter so that myself and others are not as confused by it in the future.

Since almost all of my devices use higher frequencies and the EDGE filter mode, if someone who uses some of these slower pulse rate devices could test this that would be appreciated.

Types of changes

• Bugfix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Other

Related issue or feature (if applicable): fixes

Pull request in esphome-docs with documentation (if applicable): esphome/esphome-docs#

Test Environment

• ESP32
• ESP32 IDF
• ESP8266
• RP2040
• BK72xx
• RTL87xx

Example entry for config.yaml:

# Example config.yaml

Checklist:

• The code change is tested and works locally.
• Tests have been added to verify that the new code works (under tests/ folder).

If user exposed functionality or configuration variables are added/changed:

• Documentation added/updated in esphome-docs.

[probot-esphome]

Hey there @cstaahl, @stevebaxter, mind taking a look at this pull request as it has been labeled with an integration (pulse_meter) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}

[TrentHouliston]

Should be a more complete fix for #5813 as described in that PR

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 54.05%. Comparing base (4d8b5ed) to head (7cab8d0).
Report is 500 commits behind head on dev.

Additional details and impacted files

@@            Coverage Diff             @@
##              dev    #6014      +/-   ##
==========================================
+ Coverage   53.70%   54.05%   +0.34%     
==========================================
  Files          50       50              
  Lines        9408     9554     +146     
  Branches     1654     1687      +33     
==========================================
+ Hits         5053     5164     +111     
- Misses       4056     4066      +10     
- Partials      299      324      +25     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[jesserockz]

While I appreciate you putting the effort into this file (It looks great btw), we do not want "documentation" throughout the esphome codebase in adhoc files. This is what https://esphome/esphome-docs is for.

[esphome]

Please take a look at the requested changes, and use the Ready for review button when you are done, thanks 👍

Learn more about our pull request process.

[probot-esphome]

Hey there @cstaahl, @stevebaxter, mind taking a look at this pull request as it has been labeled with an integration (pulse_meter) you are listed as a code owner for? Thanks!
_{^{(message by CodeOwnersMention)}}