Ah, okay, I get what you're saying now. And you're absolutely right - the onus is on the user to ensure you're properly documenting your code, and there is a bit of "magic" there. That said, I find Rust's docstrings pretty dang magical already so that third slash suggests to me this comment is "extra special" somehow, even if it's not how a normal doc comment is used.
I don't have the perspective of having worked on a team before, but I'm surprised to hear that you specifically omit the docstrings - that's not something I usually do when I'm copying code I didn't write specifically because I want to be sure I have all the information I need as I build on it. For this library, anyone would simply have to know that they're part of the code.
You do have the option to skip the docstrings, though, and define your help strings directly using the about attribute:
I think this circumvents the problem you're describing, but as before it's still up to your review process to ensure each field has this attribute defined.
I'd never understood why this would be preferable until now - thanks for the perspective!
For further actions, you may consider blocking this person and/or reporting abuse
We're a place where coders share, stay up-to-date and grow their careers.
Ah, okay, I get what you're saying now. And you're absolutely right - the onus is on the user to ensure you're properly documenting your code, and there is a bit of "magic" there. That said, I find Rust's docstrings pretty dang magical already so that third slash suggests to me this comment is "extra special" somehow, even if it's not how a normal doc comment is used.
I don't have the perspective of having worked on a team before, but I'm surprised to hear that you specifically omit the docstrings - that's not something I usually do when I'm copying code I didn't write specifically because I want to be sure I have all the information I need as I build on it. For this library, anyone would simply have to know that they're part of the code.
You do have the option to skip the docstrings, though, and define your help strings directly using the about attribute:
I think this circumvents the problem you're describing, but as before it's still up to your review process to ensure each field has this attribute defined.
I'd never understood why this would be preferable until now - thanks for the perspective!