Documentation override

[eirnym]

Hi, thank you for a library

Could you please add ability to override docs. I prefer to keep Rust docstrings and output documentation separate in some cases. For example, I would like to pass some additional documentation for developer which should be hidden from user. Simple comment doesn't represent it, as you have to open code itself to see if it's there in the first place.

[yanganto]

We can use /// and // here, and developer working on the source code easy to see the //, and only the simple end user will see the content of /// from the example file. And also, I have added a test case for you, you can easier to know.

Will this fix your using case?
If this is not enough please reopen the issue again, I am happy to help. 😄

[eirnym]

This is a thing I described to avoid.

User facing output is not the same as dev docs.

Dev should open docs and see the whole developer docs, while documentation for user produced should be different. These audiences are different and I'd like to avoid mixing them.

Comments are often not seen by dev as you need to know in the first place that they are there to see

PS: I have no permissions to reopen an issue in repository I don't maintain.

[yanganto]

Sorry about that, I did not notice that it is hard to reopen the issue from your end. I did not intent to remove your voice. 🙏

Let me check on this, also I just wonder if there is some feature gate can solve this issue for doc rs.

[yanganto]

My understanding is that this can be resolved through feature gates.

struct S {
  #[cfg_attr(feature = "dev-docs", doc = "This paragraph only appears when `dev-docs` feature is enabled.")]
  f: usize
}

# Multiple features
cargo doc --features "dev-docs"

# All features
cargo doc --all-features

The motivation for building the crate and exposing it as documentation for end users is to avoid verbosity and keep the project DRY. Since most of my work is open source, there is little reason to hide implementation details or doc from end users for me. More importantly, using a single source of truth for both developer and end user documentation reduces maintenance overhead and keeps everything consistent — especially important for a project with a long lifespan.
I will not close this discussion if you are still uncomfortable with this approach, but I am hoping we can reach a mutual understanding. And if my proposal does not work, please kindly let me know again. 😁

[eirnym]

I would prefer a special attribute on your side to have them both.

Something like clap provides.