General Issue: Implement roxygen roclet to add titles and descriptions to examples

[bundfussr]

Background Information

A roxygen roclet defines how the roxygen tags in the function header are processed and how the man pages are generated. A roclet should be implemented such that a @title (and a @description tag) can be added for examples. Then each example gets a subsection with title and optionally a description. This helps navigating documentation of functions with many long examples like derive_var_extreme_flag().
See https://roxygen2.r-lib.org/articles/extending.html and https://roxygen2.r-lib.org/reference/roclet.html for some guidance on implementing roxygen roclets.

Benefits:

• More examples can be added without loosing readability.
• Finding and navigating the examples is improved.
• The reference pages can be used to train AI/LLM tools which should propose admiral function calls from plain English descriptions.

Definition of Done

A roclet is implemented.

[bms63]

Assuming this is a 1.3 issue @bundfussr? Was going to tag it for 1.3 if that is the case??

[bundfussr]

Assuming this is a 1.3 issue @bundfussr? Was going to tag it for 1.3 if that is the case??

Yes, it's for 1.3.