Area
Source code generation
Basically, I find myself writing what a lot of what is essentially boilerplate. For example, if I have the following function:
pub fn foo(a: Bar) -> bool {
// stuff here.
}
I will thereafter have to expand it into something like:
/// # Foo's Bars
///
/// Will Foo a Bar if it hasn't already been Foo'd. Will not Foo a
/// if it has already been Foo'd, so this is safe to use on any Bar
/// you come across, without checking to see if it has already
/// been Foo'd.
///
/// # Example - added if needed
///
/// ```rust
/// use crate::bar::Bar;
/// fn main() {
/// let bar = Bar::new();
/// match foo(bar) {
/// true => println!("Did foo the bar"),
/// false => println!("Bar was already foo'd, not doing anything")
/// };
/// }
/// ```
///
/// # Parameters - added if needed
///
/// - `a` - A Bar that may or may not have already been Foo'd.
///
/// # Returns - added if needed
///
/// `true` iff `a` wasn't Foo'd before this call. If this call returns,
/// rather than panics, then `a` will have been Foo'd successfully.
///
/// # Panics - added if needed
///
/// Will panic if `a` has been Baz'd.
///
/// # Errors - added if needed
/// # Safety - added if needed
/// # Aborts - added if needed
/// # Undefined Behavior - added if needed
pub fn foo(a: &mut Bar) -> bool {
// stuff here.
}
// A whole bunch more functions
#[cfg(test)]
mod tests {
use super::*;
fn test_foo() {
// Some kind of test
}
}
That is a lot of boilerplate for each function, struct, union, etc. What I want is a tool that is able to analyze the contents of a module (probably via the AST) and generate the boilerplate in place as needed (kind of like how cargo fmt figures out where whitespace should be added). It should do the following:
- If there are no module-level docs, add the appropriate block at the top. Put in a
FIXME comment anywhere I need to fill something in.
- For each member of a struct, enum, union, etc., make sure that there is documentation in place.
- For each function/method, add in the docs as shown above intelligently. That is, if my function doesn’t have any parameters, don’t bother with that section. If it does have parameters, add in a single stub line for each parameter. Same for every other heading.
- For each chunk of executable code, add in a unit test stub whose contents are
assert!(false), so that I know what I need to fill in.
-
Don’t overrwrite what is already there! I want this to be an idempotent operation, so that I can run it whenever I want, kind of like how I run
cargo fmt --all on my code right before each commit.
Is there a tool for this already?
Not as far as I can tell, but I may not be looking in the right places.
If not: which tool do you think it should be included in?
cargo fmt, probably with a new switch like cargo fmt --generate_doc_stubs --generate_test_stubs
Did you manage to work around the lack of tooling?
Copy/pasting of function names, and then prefixing with test_, or copy/pasting home-grown documentation stubs, etc.
