Add support for multi-line annotations

[hedsnz]

Currently, annotations appear only to support single-line descriptions. For example, using the quickstart example with a lengthened @param field that is split across two lines:

# example.R
#* Echo the parameter that was sent in
#* @param msg The message to echo back. Lorem ipsum dolor sit amet, consectetur adipiscing elit,
#* sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. 
#* @get /echo
function(msg=""){
  [list](https://rdrr.io/r/base/list.html)(msg = [paste0](https://rdrr.io/r/base/paste.html)("The message is: '", msg, "'"))
}

plumber::pr("example.R") |>
    plumber::pr_set_docs("swagger") |>
    plumber::pr_run()

...results in the parameter documentation for msg being cut off at the end of the first line:

The message to echo back. Lorem ipsum dolor sit amet, consectetur adipiscing elit,

The same thing occurs with redoc:

library(redoc)
plumber::pr("example.R") |>
    plumber::pr_set_docs("redoc") |>
    plumber::pr_run()

The expected behaviour is for multi-line annotations to render the entire text, in the same way that roxygen documentation works. I've tried various levels of indentation for the second line, as well as adding \n to the first line, but it's always cut off.

I'm not sure whether this can be handled in plumber without upstream changes in swagger (etc.).

[slodge]

I think it would be a useful addition to plumber 👍

I think this requires a small code fix/change inside plumber...

I've started on something in slodge@7f05924 - I don't think it's quite working perfectly - I think it needs to handle blank lines in params blocks still - there's some $ pattern matching there in the existing code that I need to look at with fresh eyes tomorrow.

Also... once we do have it working (and if we know posit want to support this), then I guess we'd need some docs and some test updates too.

[slodge]

Fresh coffee this morning - so I finished this to slodge#3

I'm not going to update tests and docs at this stage... will wait on direction from maintainers/posit on that 👍

[slodge]

Note: this would definitely be a breaking change for plumber.

If we look at the existing test cases then comments currently should always bubble up to the path description:

I don't know if people actually deliberately write their plumber blocks that way - but I guess this change would have to wait for those version Editions that posit are building here - or would have to default to a FALSE option somehow.

(But the break is only in swagger user-facing comments - so probably isn't that big a deal?)