Tab indented doc comments should be fenced

[mnaser]

I am trying to create bindings for KubeadmControlPlaneTemplate using kopium, however, it seems to be failing here:

---- src/cluster_api/kubeadmcontrolplanetemplates.rs - cluster_api::kubeadmcontrolplanetemplates::KubeadmControlPlaneTemplateTemplateSpecRemediationStrategy::min_healthy_period (line 1665) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found reserved keyword `become`
 --> src/cluster_api/kubeadmcontrolplanetemplates.rs:1666:4
  |
3 | M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
  |    ^^^^^^ expected one of 8 possible tokens

error: aborting due to 1 previous error

Couldn't compile the test.
---- src/cluster_api/kubeadmcontrolplanetemplates.rs - cluster_api::kubeadmcontrolplanetemplates::KubeadmControlPlaneTemplateTemplateSpecRemediationStrategy::max_retry (line 1646) stdout ----
error: expected one of `!`, `.`, `::`, `;`, `?`, `{`, `}`, or an operator, found reserved keyword `become`
 --> src/cluster_api/kubeadmcontrolplanetemplates.rs:1647:4
  |
3 | M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
  |    ^^^^^^ expected one of 8 possible tokens

That can be manually worked around but I guess it would be nice to escape the become keyword, int hsi case:

    /// MinHealthyPeriod defines the duration after which KCP will consider any failure to a machine unrelated
    /// from the previous one. In this case the remediation is not considered a retry anymore, and thus the retry
    /// counter restarts from 0. For example, assuming MinHealthyPeriod is set to 1h (default)
    /// 
    /// 
    /// 	M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
    /// 	If M1-1 (replacement of M1) has problems within the 1hr after the creation, also
    /// 	this machine will be remediated and this operation is considered a retry - a problem related
    /// 	to the original issue happened to M1 -.
    /// 
    /// 
    /// 	If instead the problem on M1-1 is happening after MinHealthyPeriod expired, e.g. four days after
    /// 	m1-1 has been created as a remediation of M1, the problem on M1-1 is considered unrelated to
    /// 	the original issue happened to M1.
    /// 
    /// 
    /// If not set, this value is defaulted to 1h.
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "minHealthyPeriod")]
    pub min_healthy_period: Option<String>,

[mnaser]

I've updated the title of the bug report, it seems the fact tha tthey are tabbed in that they're getting parsed.

[clux]

uh, what do you mean by "tabbed in" here?

[clux]

(keywords should already automatically escaped via syn in

kopium/src/output.rs

Lines 195 to 212 in 335ac2f

	fn try_escape_name(name: String) -> Option<String> {
	if syn::parse_str::<syn::Ident>(&name).is_ok() {
	return Some(name);
	}
	let escaped_name = format!("r#{name}");
	if syn::parse_str::<syn::Ident>(&escaped_name).is_ok() {
	return Some(escaped_name);
	}
	let escaped_name = format!("r#_{name}");
	if syn::parse_str::<syn::Ident>(&escaped_name).is_ok() {
	return Some(escaped_name);
	}
	None
	}
	}

)

[mnaser]

@clux: sorry, I was not clear, I don't think it's the keywords here but the fact that in the description of the CR, the data is tabbed out, specifically, the CR will not compile with this:

    /// MinHealthyPeriod defines the duration after which KCP will consider any failure to a machine unrelated
    /// from the previous one. In this case the remediation is not considered a retry anymore, and thus the retry
    /// counter restarts from 0. For example, assuming MinHealthyPeriod is set to 1h (default)
    /// 
    /// 
    /// 	M1 become unhealthy; remediation happens, and M1-1 is created as a replacement.
    /// 	If M1-1 (replacement of M1) has problems within the 1hr after the creation, also
    /// 	this machine will be remediated and this operation is considered a retry - a problem related
    /// 	to the original issue happened to M1 -.
    /// 
    /// 
    /// 	If instead the problem on M1-1 is happening after MinHealthyPeriod expired, e.g. four days after
    /// 	m1-1 has been created as a remediation of M1, the problem on M1-1 is considered unrelated to
    /// 	the original issue happened to M1.
    /// 
    /// 
    /// If not set, this value is defaulted to 1h.
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "minHealthyPeriod")]
    pub min_healthy_period: Option<String>,

However, it will compile with this:

    /// MinHealthyPeriod defines the duration after which KCP will consider any failure to a machine unrelated
    /// from the previous one. In this case the remediation is not considered a retry anymore, and thus the retry
    /// counter restarts from 0. For example, assuming MinHealthyPeriod is set to 1h (default)
    /// 
    /// If not set, this value is defaulted to 1h.
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "minHealthyPeriod")]
    pub min_healthy_period: Option<String>,

I believe since markdown uses ``` but also a tab in order to signify code, Rust is interpreting the tabbed comments (M1 bit) as code, and trying to compile it.

[clux]

Ah. Right. That makes sense now. I guess this is our 'code detection regex' that we apply on docstrings in

kopium/src/output.rs

Lines 259 to 275 in 9245007

	pub fn format_docstr(indent: &str, input: &str) -> String {
	static RE_CODEBLOCK: OnceLock<Regex> = OnceLock::new();
	let re = RE_CODEBLOCK.get_or_init(|| {
	RegexBuilder::new(r"```.*\n([\s\S]+)\n```")
	.swap_greed(true)
	.build()
	.unwrap()
	});
	let cleaned_input = re.replace_all(input, "```text\n$1\n```");
	// TODO: maybe logic to split doc strings by sentence / length here
	format!(
	"{}/// {}",
	indent,
	cleaned_input.replace('\n', &format!("\n{}/// ", indent))
	)
	}

that needs to be smarter.

currently we only look for things that uses a proper code delimiter like triple backticks.

Don't have a bunch of time, so PRs welcome.