Require docs for public members #427
Conversation
| @@ -902,13 +919,15 @@ impl<'a> TypeEnum<'a> { | |||
| } | |||
|
|
|||
| impl<'a> TypeStruct<'a> { | |||
| /// Get name and type of each property. | |||
| pub fn properties(&'a self) -> impl Iterator<Item = (&'a str, TypeId)> { | |||
There was a problem hiding this comment.
I'm probably going to EOL this interface in the future.
| @@ -94,13 +101,15 @@ pub struct TypeEnum<'a> { | |||
| details: &'a type_entry::TypeEntryEnum, | |||
| } | |||
|
|
|||
| #[allow(missing_docs)] | |||
| /// Enum variant details. | |||
| pub enum TypeEnumVariant<'a> { | |||
| Simple, | |||
| Tuple(Vec<TypeId>), | |||
| Struct(Vec<(&'a str, TypeId)>), | |||
There was a problem hiding this comment.
| Struct(Vec<(&'a str, TypeId)>), | |
| /// Struct-type variant with named properties and types. | |
| Struct(Vec<(&'a str, TypeId)>), |
Ugh... makes me realize that there's no way to get at the description for each variant.
typify-impl/src/lib.rs
Outdated
| @@ -94,13 +101,15 @@ pub struct TypeEnum<'a> { | |||
| details: &'a type_entry::TypeEntryEnum, | |||
| } | |||
|
|
|||
| #[allow(missing_docs)] | |||
There was a problem hiding this comment.
| #[allow(missing_docs)] |
| @@ -70,6 +76,7 @@ pub struct Type<'a> { | |||
| type_entry: &'a TypeEntry, | |||
| } | |||
|
|
|||
| #[allow(missing_docs)] | |||
There was a problem hiding this comment.
I think we can document this; see inspiration below. Let me know if you'd like me to add suggestions.
There was a problem hiding this comment.
I've added the ones you've given, and added a few more.
My intention was to put #[allow(missing_docs)] where other people can replace it with real docs.
The goal of the PR isnt to document everything, but instead to ensure new enhancements must include docs at the outset.
| @@ -38,6 +42,7 @@ pub struct CliArgs { | |||
| } | |||
|
|
|||
| impl CliArgs { | |||
| /// Output path. | |||
| pub fn output_path(&self) -> Option<PathBuf> { | |||
There was a problem hiding this comment.
probably just nothing in this file should be pub since it's a command...
There was a problem hiding this comment.
CliArgs's struct fields should be documented as those docs appear on the command line --help.
IMO it is simpler to write some basic docs, rather than having guidelines for contributors when #[allow(missing_docs)] is allowed and when it isn't.
Added
#[allow(missing_docs)]for quite a few of the impl enums where I would struggle to write useful docs.