How to write doc comment for tuple struct

help
1

How do you typically document the fields of a tuple struct?

/**
 * A dice that can be rolled
 *
 * .0: number of faces
 */
#[derive(Debug, Clone, Copy)]
pub struct Dice(pub usize);

The .0 feels a bid weird, but I guess there is no better options?

2

I think that if you begin to need naming a field, you should do a "complete" struct, it won't take more space (0 cost abstraction!)

1 Like
3

How do you document a tuple struct then? Even in a simple struct Point3d(i64, i64, i64) you still need to say witch parameter correspond to which axis.

EDIT: and it's not a question of abstraction cost, but syntax cost. I my case, what I really want is to be able to do Dice<10>::roll(), but since const generics don't exists (yet) in Rust, I use instead Dice(10).roll() and Dice(faces=10).roll() would be to noisy.

4

I see

I think I would go something like this:

/// A dice that can be rolled
///
/// (number of faces)

and for Point3d:

/// (x, y, z)

But I don't know if that's idiomatic

2 Likes
5

If you create a constructor fn new, then you'd get Dice::new(10).roll() and named fields with not much syntax noise. (But if you're going to call it immediately, why not just Dice::roll(10)?)

As for the original question, I'd agree with @Geobomatic's comment that if it's not completely obvious, the idiom is that it's probably worth naming. Alternatively, even just listing the field meanings would probably be clear enough.

1 Like
6

Ideally I would like to be able to use const generics, but they don't exists yet.

struct Dice<number_of_faces: usize>;
impl<number_of_faces: usize> Dice {
    fn roll() -> usize;
    fn rolls(number_of_dices) -> Vec<usize>;
}

// usage
Dice<10>::roll(); // roll a die with 10 faces
Dice<20>::rolls(5); // roll 5 dice with 20 faces

This as all the properties I want: easy to use, and concise. I could also propagate the number of faces in the output type easily.

As a proxy, I use currently

struct Dice(usize>;
impl Dice {
    fn roll() -> usize;
    fn rolls(number_of_dices) -> Vec<usize>;
}

// usage
Dice(10).roll(); // roll a die with 10 faces
Dice(20).rolls(5); // roll 5 dice with 20 faces

This is nearly as good.

I was not using tuple struct, the interface would become messy or hard to use:

Dice::new(10).roll(); // Too much syntax

Dice.roll(10); // this is ok
Dice.rolls(20, 5); // but this isn't. How much dices with how much faces were draw?

So I will keep the tuple syntax until const generics will be available. I still need a way to document them.

7

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.