Simplify generated code module structure #138
Conversation
Remove the `generated` directory and the various re-exports. - namespace docs have been extracted from the respective `mod.rs` to `.md` files in api_generator/docs, and are inserted in the generated source file. - namespace sources are generated directly in the `src` directory - the generator can now insert generated sections in regular source files based on `GENERATE-BEGIN` and `GENERATE-END` markers. This is used to generate the namespace module list in the main `lib.rs` and merge generated with manual code in `params.rs` - generated and merged source files are listed in `src/.generated.toml` so that the generator can cleanup on start. Before considering merging generated code with special markers we experimented with the `include!()` macro, but this didn't work well: - rustfmt will not reformat include files - `mod` statement look for files relative to the source file, so include files have to be located in the same directory as their includer, while locating them in a dedicated directory would have provided a nicer organization. Merging generated sections provides a more natural source code layout.
elasticsearch/src/lib.rs
Outdated
| pub mod client; | ||
| pub mod error; |
There was a problem hiding this comment.
These are now public modules in addition to being re-exported at the crate level on line 393. Take a look at the generated docs (cargo make docs) compared to https://docs.rs/elasticsearch/7.9.0-alpha.1/elasticsearch/#modules
I think the crate is a little cleaner if these are exposed only at the crate level - the types within them are universally applicable.
There was a problem hiding this comment.
Good catch, I overlooked this while reorganizing mod declarations. Fixed in 9ba6ca2
elasticsearch/src/lib.rs
Outdated
| pub mod error; | ||
| pub mod http; | ||
| pub mod params; | ||
| pub mod root; |
There was a problem hiding this comment.
This is now a public module in addition to being re-exported at the crate level on line 393. I think the crate is a little cleaner if this exposed only at the crate level - the "root" namespace is a bit of an odd construct which effectively represents "no namespace" 🙂
api_generator/src/bin/run.rs
Outdated
| @@ -28,9 +28,9 @@ use std::{ | |||
| }; | |||
|
|
|||
| fn main() -> Result<(), failure::Error> { | |||
| // This must be run from the src root directory, with cargo run -p api_generator | |||
| // This must be run from the repo root directory, with cargo run -p api_generator | |||
There was a problem hiding this comment.
Guess we can update this now to cargo make generate-api 😃
There was a problem hiding this comment.
Indeed 😉 - done in 00efb77
api_generator/src/generator/mod.rs
Outdated
| toml::to_string_pretty(&GeneratedFiles { | ||
| written: written_files, | ||
| merged: merged_files, | ||
| })?, |
There was a problem hiding this comment.
should we make written_files and merged_files be ordinal ordered, for consistent ordering? I understand they don't need to be, but I ran cargo make generate-api on my machine and the order of entries in .generated.toml is different (possible difference in default string ordering implementation on Windows vs. non-Windows)
There was a problem hiding this comment.
Good point, replaced by a BTreeSet in 9ba6ca2 to have a stable ordering.
Remove the `generated` directory and the various re-exports. - namespace docs have been extracted from the respective `mod.rs` to `.md` files in api_generator/docs, and are inserted in the generated source file. - namespace sources are generated directly in the `src` directory - the generator can now insert generated sections in regular source files based on `GENERATE-BEGIN` and `GENERATE-END` markers. This is used to generate the namespace module list in the main `lib.rs` and merge generated with manual code in `params.rs` - generated and merged source files are listed in `src/.generated.toml` so that the generator can cleanup on start. Before considering merging generated code with special markers we experimented with the `include!()` macro, but this didn't work well: - rustfmt will not reformat include files - `mod` statement look for files relative to the source file, so include files have to be located in the same directory as their includer, while locating them in a dedicated directory would have provided a nicer organization. Merging generated sections provides a more natural source code layout. (cherry picked from commit 9d9a4fb)
Remove the `generated` directory and the various re-exports. - namespace docs have been extracted from the respective `mod.rs` to `.md` files in api_generator/docs, and are inserted in the generated source file. - namespace sources are generated directly in the `src` directory - the generator can now insert generated sections in regular source files based on `GENERATE-BEGIN` and `GENERATE-END` markers. This is used to generate the namespace module list in the main `lib.rs` and merge generated with manual code in `params.rs` - generated and merged source files are listed in `src/.generated.toml` so that the generator can cleanup on start. Before considering merging generated code with special markers we experimented with the `include!()` macro, but this didn't work well: - rustfmt will not reformat include files - `mod` statement look for files relative to the source file, so include files have to be located in the same directory as their includer, while locating them in a dedicated directory would have provided a nicer organization. Merging generated sections provides a more natural source code layout. (cherry picked from commit 9d9a4fb)
Remove the
generateddirectory and the various re-exports.mod.rsto.mdfiles in api_generator/docs, and are inserted in the generatedsource file.
srcdirectoryfiles based on
GENERATE-BEGINandGENERATE-ENDmarkers. This isused to generate the namespace module list in the main
lib.rsandmerge generated with manual code in
params.rssrc/.generated.tomlso that the generator can cleanup on start.
Before considering merging generated code with special markers we
experimented with the
include!()macro, but this didn't work well:modstatement look for files relative to the source file, soinclude files have to be located in the same directory as their
includer, while locating them in a dedicated directory would have
provided a nicer organization.
Merging generated sections provides a more natural source code layout.