Extend duration documentation

[thomas-nicolai-frequenz]

What's needed?

We need to improve the documentation for the duration parameter as shown below:

Proposed solution

message Dispatch {
  // ...

-  // Duration in seconds
+  // Duration of the dispatch in seconds. 
+  //
+  // !!! note
+  //     This field manages how long the dispatch lasts:
+  //     - `null` value indicates an infinite duration, meaning the dispatch continues indefinitely.
+  //     - A value of `0` indicates a one-time execution, which does not repeat or persist.
+  //     - Positive values specify the duration in seconds for which the dispatch should be active.
+  //
+  //     Example of how to set duration
+  //         duration_seconds: { value: 3600 } // Duration of 1 hour
+  //         duration_seconds: null // Infinite duration
+  //         duration_seconds: { value: 0 } // One-time execution
- //  uint32 duration = 7;
+ //  optional uint32 duration_seconds = 7;
}

Use cases

No response

Alternatives and workarounds

No response

Additional context

No response

[llucax]

Maybe it would be also worth clarifying that this is a duration within one run if it is a recurring dispatch. It is not related to the recurrence itself.

[thomas-nicolai-frequenz]

@leandro-lucarella-frequenz how about?

message Dispatch {
  // ...

-  // Duration in seconds
+  // Duration of the dispatch in seconds. 
+  //
+  // The duration specifies how long each occurrence of the dispatch lasts during 
+  // a single run, applies only to the individual instance and not the overall cycle of 
+  // recurring dispatches. This setting is independent of the recurrence pattern, 
+  // which is governed by separate recurrence settings.
+  // 
+  // !!! note
+  //     This field manages how long each occurrence of the dispatch lasts:
+  //     - `null` value indicates an infinite duration, meaning each dispatch occurrence 
+  //.      continues indefinitely.
+  //     - A value of `0` indicates a one-time execution for that particular occurrence, 
+  //       which does not repeat or persist beyond its initial run.
+  //     - Positive values specify the duration in seconds for each dispatch occurrence 
+  //       should be active.
+  //
+  //     Example of how to set duration
+  //         duration_seconds: { value: 3600 } // Duration of 1 hour
+  //         duration_seconds: null // Infinite duration
+  //         duration_seconds: { value: 0 } // One-time execution    
+  //
- //    uint32 duration = 7;
+ //  optional uint32 duration_seconds = 7;
}

The duration parameter is renamed to duration_seconds so its more distinct from the recurrence pattern settings, ensuring that there's less confusion between the duration of individual runs and the overall scheduling pattern. Moreover, at the top it explicitly states that the duration_seconds applies to each individual occurrence of the dispatch.

[leandro-lucarella-frequenz]

I'd remove the "Maybe it would be also worth clarifying that " ;)

[thomas-nicolai-frequenz]

Oh, sorry I've improved the above.