Stream: general

Topic: Generated code, include directives, and attributes


Josh Triplett (Dec 01 2019 at 03:37, on Zulip):

I'm trying to use a build script to generate some code. I've written the generated code into $OUT_DIR/lib-generated.rs, and src/lib.rs contains an include directive to include that. However, I ran into the issue that included files can't contain module doc comments or module-level directives like #![no_std]. Is there a well-known solution for that? What's the best way to generate a crate's source code from build.rs?

Lokathor (Dec 01 2019 at 06:40, on Zulip):

you should be able to document the module from lib.rs

/// docs here
pub mod generated{
include!(generated)
}
Lokathor (Dec 01 2019 at 06:40, on Zulip):

as for other directives, i simply placed all of them into lib.rs

Lokathor (Dec 01 2019 at 06:42, on Zulip):

also you could just totally prevent the inner module from being known and having to document it maybe

Lokathor (Dec 01 2019 at 06:42, on Zulip):

depends on how important that module was for user understanding, but for ogl33 i just make it all appear in the crate root

Josh Triplett (Dec 01 2019 at 17:19, on Zulip):

The code generation wants to generate the documentation, too.

Josh Triplett (Dec 01 2019 at 17:20, on Zulip):

I'd rather not hardcode it.

Josh Triplett (Dec 01 2019 at 17:20, on Zulip):

Ditto the directives.

gnzlbg (Dec 02 2019 at 08:34, on Zulip):

You can generate the documentation in an .md file, and include it.

gnzlbg (Dec 02 2019 at 08:36, on Zulip):

The only documentation that you can't generate is "top-level" documentation for a module that has an include! from within that include!.

gnzlbg (Dec 02 2019 at 08:37, on Zulip):

but you can have:

#![doc(include = "generated_docs.md")]
include!(generated);
Lokathor (Dec 02 2019 at 09:23, on Zulip):

markdown is good

Lokathor (Dec 02 2019 at 09:28, on Zulip):

also try this:

// lib.rs is something like this
// you make a private inner module
// and pub use the content
// the outside world doesn't generally see the intermediate level
// (it will show up in the full path of error messages)

pub use priv_includer::*;
mod priv_includer{
  include!(gen.rs)
}

// gen.rs immediately creates a pub module
// you can stick doc on this module from the outside
// and the inside should support inner attributes

/// docs for the module you want seen
pub mod the_module_you_want_seen{
  //...
}
Lokathor (Dec 02 2019 at 09:29, on Zulip):

the outside world sees it as my_crate::the_module_you_want_seen

Last update: Dec 12 2019 at 01:15UTC