Warnings about missing docs

[graelo]

Hi, thanks for this great project!

I'm just getting started with confique, and my toy crate's layout separates the binary from the lib crate

[[bin]]
name = "mybinary"
path = "src/bin/mybinary.rs"

This leads me to expose the config as a public struct: (I think it's fine but comments are welcome)

//! Configuration.

use confique;
use std::{net::IpAddr, path::PathBuf};

/// The main configuration.
#[derive(confique::Config)]     ■ missing documentation for a module
pub struct Conf {     ■■■ missing documentation for a struct field
    /// Port to listen on.
    #[config(env = "PORT", default = 8080)]
    pub port: u16,

    /// Bind address.
    #[config(default = "127.0.0.1")]
    pub address: IpAddr,

    /// Logging configuration.
    #[config(nested)]
    pub log: LogConf,
}

/// Log specific configuration.
#[derive(confique::Config)]     ■ missing documentation for a module
pub struct LogConf {     ■■■ missing documentation for a struct field
    /// Whether or not to print the logs to the console.
    #[config(default = true)]
    pub stdout: bool,

    /// File where to write the logs.
    pub file: Option<PathBuf>,

    /// Ignored modules.
    #[config(default = ["debug"])]
    pub ignored_modules: Vec<String>,
}

By the way, the generated templates are truly great, kudos!

As you can see, I'm using your example code, and I added doc comments wherever I could, but I'm getting missing docs warnings. They are triggered by my directive in lib.rs

#![warn(missing_docs)]

Indeed, cargo expand shows the following

...
    pub mod confique_partial_log_conf {
        use super::*;
        pub struct PartialLogConf {
            pub stdout: std::option::Option<bool>,
            pub file: std::option::Option<PathBuf>,
            pub ignored_modules: std::option::Option<Vec<String>>,
        }
...

Am I missing something? I'd like to keep my missing_docs directive.

Thanks!

[LukasKalbertodt]

Great to hear this library has been useful to you!

You are right, the docs on the original structs are not forwarded to the extra "partial" struct. Of course I could just do that but I'm not sure how useful that is. I could also just add #[allow(missing_docs)] to the generated module. I suppose docs could be useful, especially in IDE/editor when looking at a field of the partial struct....

I've also been thinking how this generated module should appear in the generated docs. One could either mark it #[doc(hidden)] and declare it as implementation detail. Or I would leave it visible but would add module docs describing a few useful things.

Do you have any thoughts/opinions on those two matters?

[graelo]

Hi, thanks for your prompt response!

For the 1st topic, I would not mind too much about having a #[allow(missing_docs)] in this generated module for partials, because, if I understand correctly, this part essentially parallels the existing code. At least that's my understanding of it, I hope it makes sense!

For the 2nd topic, I'm still discovering confique, so I don't have an actual opinion of what would be best for users.

Fortunately, any decision you make now on these topics, you can still revert later, based on preference or feedback.

Cheers!

[LukasKalbertodt]

Ok, I implemented something in these two commits:

• 4f72a14
• 2c19c0e

If you have time, could you check whether it works with your project now? You can do that by changing your Cargo.toml: confique = { git = "https://github.com/LukasKalbertodt/confique" }. If it works for you, then it can be released as 0.2.3.

[LukasKalbertodt]

I just released those changes as v0.2.3. As my own tests showed that the original issue is fixed, I will close this.

[graelo]

Thanks a lot. I'm sorry I did not answer before. I wanted to test your changes, but I've been drowning recently. Thanks again.