Documentation headings

[hadley]

It looks like the code generator is converting headings to:

#' **Release status**

Instead of

## Release status

Additionally, in statement_execution.R it's generating this:

#' ----
#'
#' ### **Warning: We recommend you protect the URLs in the EXTERNAL_LINKS.**
#'
#' When using the EXTERNAL_LINKS disposition, a short-lived pre-signed URL is
#' generated, which the client can use to download the result chunk directly
#' from cloud storage. As the short-lived credential is embedded in a pre-signed
#' URL, this URL should be protected.
#'
#' Since pre-signed URLs are generated with embedded temporary credentials, you
#' need to remove the authorization header from the fetch requests.
#'
#' ----
#'

and the sequences of dashes are causing this warning when documenting:

Warning: [statement_execution.R:12] @details markdown
translation failed
✖ Internal error: unknown xml node thematic_break
ℹ Please file an issue at
  https://github.com/r-lib/roxygen2/issues

If you can tell me what you're trying to achieve here, I can suggest how you might best express that in R's documentation.

[nfx]

The source text is written in markdown (see this page for another render), converted by https://github.com/databricks/databricks-sdk-go/blob/main/openapi/code/named.go#L251-L310, resulting in the comment renders.

If you could provide a set of markdwon-to-rdoc rules, would be great. if it's a PR to generator - even better.

[hadley]

Ah, if the source doesn't use headings, there's little point in patching up the markdown here. Let me contemplate the thematic_break a little more; maybe it's easier to handle in roxygen2 since all the docs are auto-generated here. (I'm actually impressed that roxygen2 already handles all the markdown you supply 😄)

[nfx]

@hadley technically we can do special comment preprocessor in the generator. up to you :)

[nfx]

@hadley so, is there anything we need to do with markdown to turn it more roxygen friendly?

[hadley]

Probably the easiest solution would be just to strip the lines that consist of only --- in the preprocessor.