#1910 Add formal time period type to documentation
Reporter
Vito
Owner
Nobody
Created
Updated
Stars
★ (1)
Tags
Status-Accepted
Priority-Medium
Type-Defect
Component-Docs
Vito
on
Details:
The config options like archive_expires_after and http_file_share_expires_after should have their own type, say time_period, which would help to understand what values are appropriate.
I think it should contain the following statements
Number of seconds:
- 10 - 10 seconds
- 1.5 * 60 - 1.5 minutes
- 60 * 60 - 1 hour
- 86400 - 1 day
- 24 * 60 * 60 + 60 - 1 day and 1 minute
Number of units:
- "1 second"
- "5 seconds"
- "10 minutes"
- "15 hours"
- "20 days"
- "25 months"
- "30 years"
Infinite number:
- "never"
Additional:
I think the short forms like "1m" should be removed from the documentation altogether.
Ref: https://hg.prosody.im/trunk/rev/80a1ce9974e5
Details: The config options like archive_expires_after and http_file_share_expires_after should have their own type, say time_period, which would help to understand what values are appropriate. I think it should contain the following statements Number of seconds: - 10 - 10 seconds - 1.5 * 60 - 1.5 minutes - 60 * 60 - 1 hour - 86400 - 1 day - 24 * 60 * 60 + 60 - 1 day and 1 minute Number of units: - "1 second" - "5 seconds" - "10 minutes" - "15 hours" - "20 days" - "25 months" - "30 years" Infinite number: - "never" Additional: I think the short forms like "1m" should be removed from the documentation altogether. Ref: https://hg.prosody.im/trunk/rev/80a1ce9974e5
Thanks for the report. Time periods do in fact have their own type as of Prosody 13.0, tho we will have to write the documentation in a way that works for 0.12 until it reaches end of life. There's some mention of the new types in the developer section https://prosody.im/doc/developers/moduleapi#moduleget_option_option_name_default_value
ChangesHi Zash, doesn't prosody:0.12 support both strings and numbers? https://github.com/prosody/prosody-docker/blob/d5987023e2c3eaf8b1ee5f0b1e864e6748d5b748/configs/prosody-0.12.cfg.lua#L201 https://github.com/prosody/prosody-docker/blob/d5987023e2c3eaf8b1ee5f0b1e864e6748d5b748/configs/prosody-0.12.cfg.lua#L275 https://github.com/prosody/prosody-docker/blob/d5987023e2c3eaf8b1ee5f0b1e864e6748d5b748/configs/prosody-0.12.cfg.lua#L230
No, in 0.12 only mod_mam had what later evolved into the standard "period" type: https://hg.prosody.im/trunk/file/0.12.5/plugins/mod_mam/mod_mam.lua#l510 mod_http_file_share in 0.12 used a number: https://hg.prosody.im/trunk/file/0.12.5/plugins/mod_http_file_share.lua#l43 statistics_interval is still always a number or the string "manual": https://hg.prosody.im/trunk/file/13.0.0/core/statsmanager.lua#l9
Quite a number of modules use this now, their docs probably need updating too. $ hg grep -l module:get_option_period plugins/mod_bosh.lua plugins/mod_c2s.lua plugins/mod_cron.lua plugins/mod_csi_simple.lua plugins/mod_external_services.lua plugins/mod_http.lua plugins/mod_http_file_share.lua plugins/mod_invites.lua plugins/mod_limits.lua plugins/mod_mam/mod_mam.lua plugins/mod_muc_mam.lua plugins/mod_register_limits.lua plugins/mod_s2s.lua plugins/mod_smacks.lua plugins/mod_tokenauth.lua plugins/mod_tombstones.lua plugins/mod_turn_external.lua plugins/mod_user_account_management.lua plugins/mod_websocket.lua plugins/muc/lock.lib.lua plugins/muc/mod_muc.lua