[Feat] loosen up doc-string syntax

[BWindey]

Currently it is not possible to split the expression and/or description of @param, @return and @require over multiple lines.

It would be great if we could do something like:

<*
    @require arg1 <= 0 && arg2 >= 0 : 
        "This function requires arg1 to be negative, and arg2 to be positive"
*>

A more complex example:

<*
    @require argument_1 & 0b1110_0000 == 0b1100_0000
        || argument_2 & 0b1100_0000 == 0b0100_0000 
        : "argument_1 should point to start of UTF8 2-byte character "
          "or argument_2 should point to start of UTF8 1-byte character"
*>

I don't know how much freedom would be possible while staying with C3s goals, but it would be great if this could be looked into.

[lerno]

<*
 @require arg1 <= 0 && arg2 >= 0 
   :  "This function requires arg1 to be negative, and arg2 to be positive"
   :  "Blah blah"  
*>

This could probably be made to parse correctly

But I think that more complex ones should be moved to macros.

[BWindey]

I agree that complex logic should be made into a macro.

[lerno]

So what syntax would you prefer?

[BWindey]

<* @require arg1 <= 0 && arg2 >= 0 : "This function requires arg1 to be negative, and arg2 to be positive" : "Blah blah"
*>

This syntax is fine. Putting a : at the beginning of each line keeps it clear that you're still doing an explanation-string.

[lerno]

@BWindey Just continuing with a string like "..." would be equally simple.

[BWindey]

How do you mean?

[lerno]

Like this:

<*
    @require arg1 <= 0 && arg2 >= 0 : 
        "This function requires arg1 to be negative,"
        " and arg2 to be positive"
*>

[BWindey]

That's good for me as well. I'll leave that up to you, as you know your language better then I do.

[BWindey]

Update from the poll on Discord: the people have decided that the syntax with just 1 : is preferable.

[lerno]

It's implemented now. Please try it out.

[BWindey]

Yes, that works now:

<*
    @require @somthing() : 
        "Helo"
        "fiew"
*>