feat: introduce the more consistent and feature-rich create function

[zhongwencool]

Features

• Comprehensive Documentation: Added extensive documentation using ?MODULEDOC and ?DOC macros to explain the module's purpose, functions, parameters, and return values. This includes:

  • Module-level documentation for ecron.
  • Detailed documentation for each exported function, including create/3, create/4, send_after/3, send_interval/2, send_interval/3, send_interval/4, delete/1, delete/2, deactivate/1, activate/1, deactivate/2, activate/2, statistic/0, statistic/1, statistic/2, predict_datetime/2, predict_datetime/4, reload/0, reload/1, and parse_spec/2.
  • Examples in both Erlang and Elixir for most functions.
  • Clear explanations of options, return values, and potential errors.

• Deprecated Functions: Marked older functions (add/3, add/4, add/6, add/7, add_with_time/5, add_with_time/6, add_with_count/3, add_with_count/5, send_interval/5, send_interval/7, send_interval/8) as deprecated, advising users to use create/4 and send_interval/4 instead.

• Enhanced create/4 Function:

  • Added detailed explanations for the Opts parameter, including register, start_time, end_time, singleton, max_count, and max_runtime_ms.
  • Included a note about automatic job removal when max_count is reached.
  • Added a TimeRange info box explaining the constraints on start_time and end_time.
  • Added an example of handling invalid time configurations.

• Enhanced send_interval/4 Function:

  • Added a note indicating that this is a repeatable timer and can be seen in statistic/0 results.
  • Clarified that ecron:delete/1 should be used to cancel the timer, not erlang:cancel_timer/1.

• Enhanced statistic/2 Function:

  • Provided a detailed explanation of the statistic() return value, including descriptions of ok, crashed, skipped, and aborted states.

• Time Zone Configuration:

  • Added documentation for configuring the time zone using the time_zone application environment variable.
  • Explained the difference between local and utc time zone settings.

• Telemetry Integration:

  • Documented the use of Telemetry for instrumentation and logging.
  • Provided a table of Telemetry events, including success, activate, deactivate, delete, crashed, skipped, aborted, global,up, and global,down.
  • Explained how to enable or disable logging via the log configuration.
  • Provided guidance on writing custom Telemetry event handlers.

• Internal Functions:

  • Added ?DOC(false) to internal functions to hide them from the generated documentation.

Changes

• Refactored add Functions: Replaced multiple add functions with a unified create function for better consistency and maintainability.

• Improved Error Handling: Added more specific error handling and return values for various functions.

• Code Clarity: Improved code readability by adding comments and using more descriptive variable names.

Deprecations

• The following functions have been marked as deprecated:
  • add/3, add/4, add/6, add/7
  • add_with_time/5, add_with_time/6
  • add_with_count/3, add_with_count/5
  • send_interval/5, send_interval/7, send_interval/8

Purpose

These changes significantly enhance the usability and maintainability of the ecron library by providing comprehensive documentation, improving code structure, and integrating Telemetry for better monitoring and logging. The deprecation of older functions encourages users to adopt the more consistent and feature-rich create function.

[codecov]

Codecov Report

Attention: Patch coverage is 88.72180% with 15 lines in your changes missing coverage. Please review.

Project coverage is 96.80%. Comparing base (23536a1) to head (9f08b3e).
Report is 21 commits behind head on main.

Files with missing lines	Patch %	Lines
src/ecron.erl	87.65%	10 Missing ⚠️
src/ecron_spec.erl	86.48%	5 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #22      +/-   ##
==========================================
- Coverage   99.48%   96.80%   -2.68%     
==========================================
  Files           5        6       +1     
  Lines         584      658      +74     
==========================================
+ Hits          581      637      +56     
- Misses          3       21      +18     

Flag	Coverage Δ
erlang-	96.80% <88.72%> (-2.68%)	⬇️
os-	96.80% <88.72%> (-2.68%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

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