Expose generated modules as public

[raffomania]

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?

[GuillaumeGomez]

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. :)

[raffomania]

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 :)

[GuillaumeGomez]

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")));

[raffomania]

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?

[GuillaumeGomez]

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.

[raffomania]

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.

[GuillaumeGomez]

Well, I don't get why you want to do that in the first place so...