How should doc comments be spread over multiple elements? [closed] - rust

Question

Closed. This question is opinion-based. It is not currently accepting answers.
Want to improve this question? Update the question so it can be answered with facts and citations by editing this post.
Closed 9 months ago.
Improve this question
I need to document a piece of code that is 3-fold. I have an enum element, an associated constructor and a method that uses the enum to do work. Here is a minimal example:
use regex::{Error, Regex};
pub enum Element {
And {
lhs: Box<Element>,
rhs: Box<Element>,
},
Value {
regex: Regex,
},
}
impl Element {
pub fn new_and(lhs: Element, rhs: Element) -> Self {
Element::And {
lhs: Box::new(lhs),
rhs: Box::new(rhs),
}
}
pub fn new_value(regex: &str) -> Result<Self, Error> {
let regex = Regex::new(regex)?;
Ok(Element::Value { regex })
}
pub fn is_match(&self, values: &Vec<String>) -> bool {
match self {
Element::And { lhs, rhs } => lhs.is_match(values) && rhs.is_match(values),
Element::Value { regex } => {
for value in values {
if regex.is_match(value) {
return true;
}
}
false
}
}
}
}
fn main() {}
There definitely needs to be a comment on new_value() to document the possible error. But where should I put information on how the actual element is evaluated?
Put this also in the comment of new_value() to have all in one place?
Put it in a comment for Element::Value and is_match() only says that elements are
evaluated as documented there?
Put all evaluation information for all enum values in the comment for is_match() and leave Element::Value empty?
Repeat the evaluation information in all 3 locations?

Answer 1

Disclaimer: A lot of this will come down to personal preference and taste, there's not really any hard and fast rules
That being said, I like to look at the standard library's documentation for inspiration.
Generally, if a function returns a Result, some explanation of when it returns an error is probably a good idea. For example: Returns an error if the regex fails to parse. You could also look at the docs for Regex::new to see what they say about it.
When documenting the behaviour of is_match, you should probably put the comment on is_match.
But I'd also suggest putting a more comprehensive comment (preferably with a usage example) either in the module (with //! at the top) or on pub enum Element. Examples are really underrated IMO, and even a simple one can really help a reader to understand the purpose of this type.
For example, the docs for String (https://doc.rust-lang.org/std/string/struct.String.html) have quite a lot of detail on various uses of String as doc comments on the String struct itself.