Document Enumerations

[tokio-rs]

Document Enumerations

[danburkert]

Forgot to mention - there are other helper methods as well. Wherever an Enumeration is used as a field in a Message, the message will have an 'accessor' methods to get/set the value as the proper type. For instance, the Field struct contains a Cardinality field and the following methods:

impl Field {
  pub fn cardinality(&self) -> Cardinality;
  pub fn set_cardinality(&mut self, value: Cardinality);
}

Note that the first of these will return the default value (the first variant if otherwise unspecified) if the i32 value is out of range.

[danburkert]

Hi @dvtomas, thanks for opening this issue, I agree the docs should be improved in this area. The ergonomic helpers for enums were added after I wrote that bit in the readme, and I never went back and filled it in.

Toward your immediate issue, the best way to see what's available is to run rustdoc on the types and see the methods which they expose. In the case of a PhoneType enum, it will expose a pair of methods which help convert from i32:

impl PhoneType {
  pub fn is_valid(value: i32) -> bool;
  pub fn from_i32(value: i32) -> Option<PhoneType>;
}

You can see a concrete example here.

As for the Enumeration trait, there is actually no such thing. derive(Enumeration) is a trick which allows prost to generate these methods for enum types, but there's no corresponding trait.

I'm going to leave this issue open to track improving the enum docs.

[dvtomas]

Thank you for the info! It's a neat trick to use rustdoc, I didn't know it also documents derived and macro-generated code.

[sdbondi]

How about From<i32> be implemented for enums?

So that this would work:

match phone_type.into() {
   PhoneType::Mobile => {},
  // etc.    
  _ => {}
}

Methods like from_xxx are often implemented as From<Xxx> in rust.

EDIT: Just realised that from_i32 returns an Option. TryFrom<i32> could work but isn't as ergonomic

match phone_type.try_into().ok() {
   Some(PhoneType::Mobile) => {},
  // etc.    
  _ => {}
}

I see why this wasn't implemented this way - nevermind :)

[markmandel]

Can someone please provide an example on how to do do the rustdoc trick? I'm scouring documentation, and I can't seem to find the right combination of arguments 😞

I was hoping that cargo doc --open --document-private-items would do the job, but seems like it's not the case.

(Although the comments above definitely helped!, so thank you for that!)