Add doc comment to hiding portions of code example

[mandeep]

fixes #50816

Not sure if this is all that's needed, but I think it's a good start. One thing to note is that the code block is a text block where it could possibly be a rust block.

[rust-highfive]

r? @steveklabnik

(rust_highfive has picked a reviewer for you, use r? to override)

[GuillaumeGomez]

Why is there a println!?

[steveklabnik]

yes, r=me with this line removed :)

[jamesray1]

LGTM!

[steveklabnik]

yes, r=me with this line removed :)

[mandeep]

The foo function is there to show how to hide code. I wanted to add the println to show how normal code would look like in addition to hidden code.

[GuillaumeGomez]

Then you definitely need to update the next code example as well. But that seems really strange. Why would you put a doc comment on a hidden function? Doesn't make sense to me...

[mandeep]

The PR attempts to show users that one needs doc comments on all of their example code so that they don't write something like the following:

/// # Examples
/// /// Some documentation
# fn foo() {}
/// println("Hi");

[steveklabnik]

@mandeep that makes sense, but I'd prefer the examples to have actual syntax, then. You need curlies, for example.

[mandeep]

@steveklabnik Are curly braces needed somewhere besides the foo function?

[mandeep]

I discussed this on IRC and there may have been confusion with my example in my comment that contains code. I've updated the example to match the commit of the PR.

[GuillaumeGomez]

I have to admit that I still don't understand at all why there is a doc comment on a hidden function in an example. Or even why there is a doc comment in an example...

[pietroalbini]

Ping from triage! What's the status on this?

[mandeep]

@GuillaumeGomez maybe an example will help:

/// Find the barycentric coordinates of the given point with respect to the given triangle
///
/// # Examples
///
/// ```
/// let points =  vec![Vector3::new(0, 0, 0), Vector3::new(2, 2, 2), Vector3::new(0, 2, 2)]
/// let point = Point3::new(1.0, 1.0, 0.0);
/// let barycentric_coordinates: Point3<f64> = find_barycentric(&points, &point);
/// ```
///
fn find_barycentric(points: &Vec<Point3<f64>>, point: &Point3<f64>) -> Point3<f64> {
    let u = Vector3::new(points[2].x - points[0].x, points[1].x - points[0].x, points[0].x - point.x);
    let v = Vector3::new(points[2].y - points[0].y, points[1].y - points[0].y, points[0].y - point.y);

    let w = u.cross(&v);

    if (w.z).abs() < 1.0 {
        return Point3::new(-1.0, 1.0, 1.0);
    } else {
        return Point3::new(1.0 - (w.x + w.y) as f64 / w.z as f64, w.y as f64 / w.z as f64, w.x as f64 / w.z as f64);
    }

}

As for the hidden function, the docs being changed have a full example of hidden functions: https://doc.rust-lang.org/rustdoc/documentation-tests.html#hiding-portions-of-the-example

[GuillaumeGomez]

I still don't get it. :-/

[mandeep]

The use case is not immediately apparent, but since this omission is causing problems I think we need to add this commit. If you think more information is needed, let me know and I'd be happy to add more.

[GuillaumeGomez]

Ok, then let's just move forward.

@bors: r+ rollup

[bors]

📌 Commit 8d74cf8 has been approved by GuillaumeGomez