fix: cairo-doc parser extraction of comment from doc line

[cairoIover]

Closes #7014

cc @mkaput for review

[reviewable-StarkWare]

This change is 

[mkaput]

Reviewed 3 of 4 files at r1, 1 of 1 files at r2, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @cairoIover, @orizi, and @wawel37)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

        //   block, instead of assuming just one space.
        // Require a space after the marker (e.g. "/// " or "//! ")
        if let Some(content) = dedent.strip_prefix(&format!("{} ", comment_marker)) {

I just thought about this and I realised my suggestion how to solve this in the issue was actually wrong. This code forbids the following, which although looks bad is not wrong thing to be honest:

///A thing.
///
///Notice no space.
fn foo() {}

I've verified and this is picked up by rustdoc. So the logic must probably be more sophisticated. Maybe strip the marker and strip whitespace as we did, but reject lines that start with /? @wawel37 wdyt?

[wawel37]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @mkaput and @orizi)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

Previously, mkaput (Marek Kaput) wrote…

I just thought about this and I realised my suggestion how to solve this in the issue was actually wrong. This code forbids the following, which although looks bad is not wrong thing to be honest:

///A thing.
///
///Notice no space.
fn foo() {}

I've verified and this is picked up by rustdoc. So the logic must probably be more sophisticated. Maybe strip the marker and strip whitespace as we did, but reject lines that start with /? @wawel37 wdyt?

That's right, this one should be working as it would be working with a whitespace:

///Example doc comment that works as comment below
/// A comment with assumption that there's always a whitespace between a prefix and the actual comment.

When it comes to the solution that excludes just the lines that start with / after the prefix is not that perfect imho. Correct me if I am wrong, but I've seen also comment line separators like

///==============
/// Actual comment
///==============

///############
/// Another example
///############

and so on.

I've also checked how it's handled by cargo doc, and it works exactly as @mkaput mentioned. Only lines that start with / after the marker are being ignored. Like like:

///==============
///--------------
///##############

are still being extracted.

In conclusion:
Imo @mkaput is right and we should just ignore lines with / right after the marker and let the user write such docs:

///No space comment

[wawel37]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @mkaput and @orizi)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

Previously, wawel37 (Mateusz Kowalski) wrote…

That's right, this one should be working as it would be working with a whitespace:

///Example doc comment that works as comment below
/// A comment with assumption that there's always a whitespace between a prefix and the actual comment.

When it comes to the solution that excludes just the lines that start with / after the prefix is not that perfect imho. Correct me if I am wrong, but I've seen also comment line separators like

///==============
/// Actual comment
///==============

///############
/// Another example
///############

and so on.

I've also checked how it's handled by cargo doc, and it works exactly as @mkaput mentioned. Only lines that start with / after the marker are being ignored. Like like:

///==============
///--------------
///##############

are still being extracted.

In conclusion:
Imo @mkaput is right and we should just ignore lines with / right after the marker and let the user write such docs:

///No space comment

also FYI:

//!#############################

This kind of comment results in an error when using cargo doc

[mkaput]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @orizi and @wawel37)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

Previously, wawel37 (Mateusz Kowalski) wrote…

also FYI:

//!#############################

This kind of comment results in an error when using cargo doc

hmm, important case to also consider. no idea what should happen here (feel free to copy rustdoc):

/// This is a documentation block.
///
/// This is some summary, wait for this:
/////////////////////////////////////////////////
/// BANG!

[cairoIover]

Reviewable status: 1 of 4 files reviewed, 1 unresolved discussion (waiting on @mkaput and @orizi)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

Previously, mkaput (Marek Kaput) wrote…

hmm, important case to also consider. no idea what should happen here (feel free to copy rustdoc):

/// This is a documentation block.
///
/// This is some summary, wait for this:
/////////////////////////////////////////////////
/// BANG!

Done.

New logic is: don't count a comment line that starts with a / as a valid comment line.

[mkaput]

Reviewed 3 of 3 files at r3, all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @orizi)

---

crates/cairo-lang-doc/src/db.rs line 404 at r2 (raw file):

Previously, cairoIover wrote…

Done.

New logic is: don't count a comment line that starts with a / as a valid comment line.

Thank you

[wawel37]

Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @orizi)

[orizi]

Reviewed all commit messages.
Reviewable status: complete! all files reviewed, all discussions resolved (waiting on @cairoIover)