GuillaumeGomez
Expose generated modules as public
I have a snippet like this:
pub struct User {
username: String
}
Included using doctest like this:
// In module docs.rs
doctest!("doc/users.md", users);
Now in the same users.md file, I'd like to reference the User struct from another code block like so:
use docs::users::User;
let user = User { username: "gaston_lagaffe" };
This seems to almost work, except the module generated by doc_comment is not marked as pub and thus not accessible from other modules. Could you imagine adding a way to expose the module? How would you go about implementing this?
I'm a bit lost. Your content from users.md is included as a doc comment, meaning it's not rust code and cannot be used as such. So even if I make the module public, you won't be able to use this type. Another approach could be like this:
#[cfg(doctest)]
pub struct User {
username: Strin
}
Then you can use this type in other (doc) tests.
PS: I loved the reference to Gaston Lagaffe. Really loved this comic. :)
Right, I think I had the wrong image of how the macro works in my mind.
The snippet you shared would still have to reside in a .rs file, which would make it separate from the text in the .md file - I'm looking for a way to "build up" code in the docs themselves, similar to jupyter notebooks or literate programming. Maybe this is a little out of doc_comment's intended scope?
Rad that you liked Gaston as well :)
It doesn't need to reside in a .rs at all. It can reside in whatever you want. I just double-checked the docs just in case and it's showing a .md inclusion.
If you want to concatenate files, you can always do something like this (I think it works, to be confirmed):
#[cfg(doctest)]
doc_comment!(concat!(include_str!("file1.md"), include_str!("file2.md")));
Now I'm a bit lost - since markdown files included via doc_comment! will be included as doc comments, there wouldn't be any way to reference structs defined in markdown files from anywhere, or am I missing something?
If your markdown file look like this:
pub struct Something;
Then you can also include this as rust source code since it's literally rust source code.
Oh I see, but this would prohibit writing text as usual in that markdown file, right? Something like this:
See the following struct as an example:
pub struct Something;
More documentation text here
If this is not possible, why use markdown at this point? Since you're syntactically bound to rust, you might as well write a normal rust module.