feat: make libdocgen fail if a binding lacks a doc string

The --merciful option allows this if the user really wants it.

Signed-off-by: Lars Wirzenius <liw@liw.fi>
Sponsored-by: author

2 files changed, 21 insertions, 3 deletions

diff --git a/src/bin/subplot.rs b/src/bin/subplot.rs
index 40f0f55..37545a5 100644
--- a/src/bin/subplot.rs
+++ b/src/bin/subplot.rs
@@ -393,6 +393,10 @@ struct Libdocgen {
     /// If not specified, subplot will try and find a unique template name from the document
     #[clap(name = "TEMPLATE", long = "template", short = 't')]
     template: Option<String>,
+
+    /// Be merciful by allowing bindings to not have documentation.
+    #[clap(long)]
+    merciful: bool,
 }
 
 impl Libdocgen {
@@ -413,7 +417,7 @@ impl Libdocgen {
             doc.push_binding(b);
         }
 
-        std::fs::write(&self.output, doc.to_markdown())?;
+        std::fs::write(&self.output, doc.to_markdown(self.merciful)?)?;
 
         debug!("libdogen ends successfully");
         Ok(())
@@ -437,13 +441,20 @@ impl LibDoc {
         self.bindings.push(binding.clone());
     }
 
-    fn to_markdown(&self) -> String {
+    fn to_markdown(&self, merciful: bool) -> Result<String> {
         let mut md = String::new();
         md.push_str(&format!("# Library `{}`\n\n", self.filename.display()));
         for b in self.bindings.iter() {
             md.push_str(&format!("\n## {} `{}`\n", b.kind(), b.pattern()));
             if let Some(doc) = b.doc() {
                 md.push_str(&format!("\n{}\n", doc));
+            } else if !merciful {
+                return Err(SubplotError::NoBindingDoc(
+                    self.filename.clone(),
+                    b.kind(),
+                    b.pattern().into(),
+                )
+                .into());
             }
             if b.types().count() > 0 {
                 md.push_str("\nCaptures:\n\n");
@@ -452,7 +463,7 @@ impl LibDoc {
                 }
             }
         }
-        md
+        Ok(md)
     }
 }
 
diff --git a/src/error.rs b/src/error.rs
index 6859aa4..5c72879 100644
--- a/src/error.rs
+++ b/src/error.rs
@@ -50,6 +50,13 @@ pub enum SubplotError {
     #[error("binding file failed to parse: {0}")]
     BindingFileParseError(PathBuf, #[source] Box<SubplotError>),
 
+    /// Binding lacks documentation.
+    ///
+    /// Add a `doc` field to the binding with text the documents the
+    /// binding.
+    #[error("binding lacks documentation: {0}: {1} {2}")]
+    NoBindingDoc(PathBuf, crate::StepKind, String),
+
     /// Scenario step does not match a known binding
     ///
     /// This may be due to the binding missing entirely, or that the