Well, I thought I understood how to document my code, but apparently not. A friend who is collaborating with me on my Question Bank Creator project sent me some documented code as a suggestion for some changes that would help the project. It looks good on the surface, but I thought it would be easier to read if I ran it through cargo doc –open. So, I did that and didn’t get anything even close to the documentation behind my friend’s ///'s. Consider this snippet:
```
/// This is a test of documentation with cargo doc
///
/// You do know the rhyme, don't you?
/// This little piggy went to market,
/// this little piggy stayed home,
/// this little piggy had roast beef,
/// this little piggy had none,
/// and this little piggy went wee, wee, wee,
/// all the way home.
///
struct Piggy {
toes: u32,
eyes: u32,
name: String,
}
/// The function below is fake
///
pub fn fake_function() {
println!("This little piggy went to market");
}
```
When I run cargo doc –open I don’t get any documentation and in the left panel is a list of seemingly every Rust crate in existence. (BTW there are zero dependencies in the Cargo.toml file for this folder.) So my question is First, why isn’t the documentation showing up and, Second, how do I fix it?
By default, when you run cargo doc --open it will open to the page for your package's library crate (src/lib.rs). It seems like yours does have some public, documented items like pub struct Wdgts and pub mod banks. There should be a list of those items, with the first paragraph of documentation beside them.
In the code block you posted here, Piggy will not be in the documentation because it is not public, but fake_function will. But, they will not show up at all if this code is not public.
Can you post a screenshot, and more context like exactly what directory you ran cargo doc --open in to test?
I don’t get any documentation and in the left panel is a list of seemingly every Rust crate in existence. (BTW there are zero dependencies in the Cargo.toml file for this folder.)
The crate list in the documentation will include all transitive dependencies of the workspace you are in — not just the package. Your Question-Bank-Creator doesn't appear to belong to a workspace, but it does have several dependencies.
To help you, we need to know more about:
exactly what code/configuration you ran cargo doc --open for, and
what you are seeing that doesn't match what you wanted.
Actually, your reply fixed it for me. You said that all elements needed to be public, so I did that first. Then I moved the code over to lib.rs (it had originally been in main.rs). The folder I’m using isn’t a part of QBC. It’s just an empty project folder I call throwaway that I use to experiment with code. I took the little snippet listed above, modified it as you suggested above, created a simple main() function, and it all works now. I’ll do the same with my friend’s code and see how that works out. I’m just looking for readability here, nothing big.