How do I make a function visible in the documentation

I added a new pub fn foo2() in a file named foo.rs, and added some documentation for it with /// some doc above it. The file foo.rs already had a pub fn foo() inside. When running cargo doc, I still see the documentation for foo, but not for foo2. If I add the flag --document-private-items, the documentation for foo2 appears. What am I doing wrong? I thought that adding pub was enough.

is foo2 a member function of a private type? If so it won't be documented wihtout --docuement-private-items

Both foo and foo2 are at the top level of the file. They are not part of an impl.

Is the module private? Maybe foo is being re-exported from somewhere else.

I don't understand how/what exactly mod means. There is no mod keyword in foo.rs, so I guess the whole file is implicitly in the foo mod. foo.rs is in the src folder, and there is mod foo;.

@RustyYato I also took the opportunity to thanks you. This isn't the first time you help me (with other members of this forum) in a really diligent manner. It is extremely appreciated.

1 Like

Ok, so I'll give an example for how mod works

Let's say your filesystem looks something like this,

my_crate/
 +- src/
 |   +- main.rs
 |   +- foo.rs
 |   +- bar.rs
 +- ..
 .
 .
// main.rs

// this is a module declaration
// in this case, because it isn't marked `pub`, it won't be shown in the docs
// and all items inside it won't be shown in the docs unless they are re-exported
// somewhere else
mod foo;

// re-export func1 from module foo
pub use foo::func1;
// foo.rs

// This module is a submodule of main because
// we declared it so in main.rs Rust will never
// automatically infer the module hierarchy

// two pub functions, func1 will be shown in the
// docs because it was re-exported but func2
// won't because there is not exposed in any
// way. It is effectively private.
pub fn func1() {}
pub fn func2() {}
// bar.rs

// this is not a submodule of main, because it wasn't
// declared in main so nothing inside it will be shown in the docs

Thanks

I finally understood. The only place inside src/ where I found a pub use [...] foo; is in src/algo/mod.rs: pub use super::foo::foo;. So I tried to mimic it, with success. I try to add pub use super::foo::foo2.

This feels quite backward for me that a submodule export one of its parent and make it visible to the world. Anyway, I think I slowly start to understand how the visibility works in rust. For some reason, it is really hard to *click*.

You could also make the entire sub-module public by doing pub mod foo

Good idea.

This topic was automatically closed 90 days after the last reply. New replies are no longer allowed.