wrap_comments = true breaks markdown tables

[virtualritz]

This is a regression. See #4210 and #4607.

/// # Example
///
/// A typical format for a pixel containing two such layers, an *RGBA* **color**
/// & **alpha** output layer and a world space **normal**, will look like this:
///
/// [`name`](Layer::name()) | [`depth`](Layer::depth())                             | [`offset`](Layer::offset())
/// ------------------------|-------------------------------------------------------|----------------------------
/// `Ci`                    | [`ColorAndAlpha`](LayerDepth::ColorAndAlpha)(`rgba`)  | `0`
/// `N_world`               | [`Vector`](LayerDepth::Vector)(`xyz`)                 | `4`

Using rustfmt 1.7.0-nightly (df871fb 2023-10-24) this becomes:

/// # Example
///
/// A typical format for a pixel containing two such layers, an *RGBA* **color**
/// & **alpha** output layer and a world space **normal**, will look like this:
///
/// [`name`](Layer::name()) | [`depth`](Layer::depth())
/// | [`offset`](Layer::offset())
/// ------------------------|-------------------------------------------------------|----------------------------
/// `Ci`                    |
/// [`ColorAndAlpha`](LayerDepth::ColorAndAlpha)(`rgba`)  | `0` `N_world`
/// | [`Vector`](LayerDepth::Vector)(`xyz`)                 | `4`

I just noticed this broken in the docs of my nsi crate.
I published the current version on 19.04.2023. So this has been broken since at least six months, I'd wager.

[ytmimi]

@virtualritz Thanks for reaching out. rustfmt isn't currently parsing markdown constructs like GitHub Flavored Markdown Tables. A heuristic based fix was added for this back in #5475, but it's not perfect. In order for it to work properly lines that denote a table need to start with leading | characters.

This should prevent rustfmt from reformatting your table:

/// # Example
///
/// A typical format for a pixel containing two such layers, an *RGBA* **color**
/// & **alpha** output layer and a world space **normal**, will look like this:
///
/// | [`name`](Layer::name()) | [`depth`](Layer::depth())                             | [`offset`](Layer::offset())
/// |-------------------------|-------------------------------------------------------|----------------------------
/// | `Ci`                    | [`ColorAndAlpha`](LayerDepth::ColorAndAlpha)(`rgba`)  | `0`
/// | `N_world`               | [`Vector`](LayerDepth::Vector)(`xyz`)                 | `4`

[virtualritz]

This also breaks raw code snippets in lists:

//! * Dynamically link against `lib3delight`.
//!
//!   * `lib3delight` becomes a dependency. If it cannot be found your lib/app
//!     will not load/start.
//!
//!   * The feature is called `link_lib3delight`.
//!
//!   * You should disable default features (they are not needed/used) in this
//!     case:
//!
//!     ```toml
//!     [dependencies]
//!     nsi = { version = "0.7", default-features = false, features = ["link_lib3delight"] }
//!     ```  

wrap_comments = true turns this into:

//! * Dynamically link against `lib3delight`.
//!
//!   * `lib3delight` becomes a dependency. If it cannot be found your lib/app
//!     will not load/start.
//!
//!   * The feature is called `link_lib3delight`.
//!
//!   * You should disable default features (they are not needed/used) in this
//!     case:
//!
//!     ```toml
//!     [dependencies]
//!     nsi = { version = "0.7", default-features = false, features =
//! ["link_lib3delight"] }     ```

[ytmimi]

That's a duplicate of #5746. Again this is a limitation of how rustfmt handles markdown constructs.