[Question] Best way to provide custom description formatting?

[Mike Solomon]

In our PicoCLI app, we have many different options that can often be confusing for users due to the complexity of the input. For instance, we have an option called --bazel-rule that expects a bazel rule with a format similar to: //:java-maven-lib.

I've found that trying to put everything in the description without new lines makes it difficult to read and can often result in strange line-wrappings.

I've also found that manually adding in newlines like this:

@Option(names = "--bazel-rule",
        description = "Specifies a bazel rule expression.\n\n" +
                      "@|bold Example|@: //:java-maven-lib\n")
private String bazelRule;

Makes the description much easier to read in the command-line itself (and in auto-generated man pages). However, it can be easy to miss adding a \n at the end of the option descriptions or \n\n before the examples. When people miss that, it ends up looking funky as some options have newlines and others don't.

Ideally, I could add something like:

@Option(names = "--bazel-rule",
        description = "Specifies a bazel rule expression.")
@Example("//:java-maven-lib")
private String bazelRule;

And have new lines put in place automatically by the @Example annotation. Or perhaps something like:

@Option(names = "--bazel-rule",
        description = formattedDescription("Specifies a bazel rule expression.", "//:java-maven-lib")
private String bazelRule;

But, when I tried that, I got an error that the description must be constant.

Does something like this already exist in PicoCLI and I'm just missing it? Or is the best option to do something like writing a custom annotation processor? Or maybe something else altogether? Any advice would be greatly appreciated :D

Thanks for your time!

Edit:
Wanted to point out that I did look at the CustomLayout doc and the example project - but it didn't seem to be quite what I was wanting. Maybe I should explore that more, though?