Bindgen produces #[doc = "foo\nbar"] doc comments instead of multiline doc comments

[Manishearth]

This behavior changed in https://github.com/rust-lang/rust-bindgen/commit/f160d11d56007fe1b1125d04f0cb31af0b18fc6e

Bindgen used to produce doc comments like this:

extern "C" {
  #[doc = "foo"]
  #[doc = "bar"]
  fn baz();
}

but now these doc comments look like this:

extern "C" {
  #[doc = "foo\nbar"]
  fn baz();
}

which is much less readable. We have documentation on normalizing doc comments, but not everyone is using a nightly rustfmt. This change does not seem intentional but rather collateral damage in that feature, perhaps it's worth bringing the old behavior back.

[rich-ayr]

I think this is a sensible default as it removes unnecessary line noise. Most people won't go through the trouble of parsing multiple doc tags in a real scenario, they'll use rustdoc or their IDE. The normalized comments are definitely useful for a quick lookup by navigating to the definition, but I don't see this for #[doc] tags; they're not meant for humans.

[Manishearth]

I don't really find this to be unnecessary line noise.

The #[doc] tags are produced by bindgen after parsing doc comments on the C++ side: they're taking comments meant for humans and turning them into this tag. #[doc = ""] isn't great, but having it linebroken is better than nothing.

[jschwe]

FYI, you can use rustfmt (nightly) with the following configuration to normalize comments to the standard /// style:

unstable_features = true
normalize_comments = true
normalize_doc_attributes = true

Edit: Sorry, just noticed the OP already mentioned that.

[emilio]

cc @pvdrz