Add documentation for struct fields #603
Conversation
rkyv_derive/src/archive/struct.rs
Outdated
| let field_doc = format!( | ||
| "The archived counterpart of [`{}:{}`]", | ||
| name, | ||
| field_name.map_or("unnamed".to_string(), |s| s.to_string()) |
There was a problem hiding this comment.
unnamed fields should probably be better handled with their indices, but I'll continue after a validation.
There was a problem hiding this comment.
We should be able to get the index by doing for (i, field) in fields.iter().enumerate() and ident.map_or_else(|| &index as &dyn Display, |name| &name as &dyn Display). Coercing to &dyn Display is a little more complicated than converting both to a string, but it does technically avoid an allocation. I also checked that you can make doc links to tuple fields by using their index as the name.
There was a problem hiding this comment.
Thanks! Should we have testing on those documentations ?
It's a tiny bit tricky to test because we should probably create a new library dedicated to testing which should deny missing docs 🤔 ; maybe better to leave for another PR?
rkyv_derive/src/archive/struct.rs
Outdated
| let field_doc = format!( | ||
| "The archived counterpart of [`{}:{}`]", | ||
| name, | ||
| field_name.map_or("unnamed".to_string(), |s| s.to_string()) |
There was a problem hiding this comment.
We should be able to get the index by doing for (i, field) in fields.iter().enumerate() and ident.map_or_else(|| &index as &dyn Display, |name| &name as &dyn Display). Coercing to &dyn Display is a little more complicated than converting both to a string, but it does technically avoid an allocation. I also checked that you can make doc links to tuple fields by using their index as the name.
Co-authored-by: David Koloski <[email protected]>
Related to #596
Tests
Run this branch with
cargo expand ArchivedTest -p rkyv --example readmeto find the added documentation.An automated test with
deny(missing_docs)would be a great addition but let's discuss first.