From cdb53c27c8cd024b4b310b91bd406cc0de3a3b7f Mon Sep 17 00:00:00 2001
From: William Woodruff <william@yossarian.net>
Date: Sat, 17 May 2025 13:44:13 -0400
Subject: [PATCH] chore: enable missing_docs lint for
 github-actions-expressions (#807)

---
 Cargo.lock                                   |  2 +-
 crates/github-actions-expressions/Cargo.toml |  2 +-
 crates/github-actions-expressions/src/lib.rs | 35 ++++++++++++++------
 3 files changed, 27 insertions(+), 12 deletions(-)

diff --git a/Cargo.lock b/Cargo.lock
index 65477810..9c709120 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -749,7 +749,7 @@ checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f"
 
 [[package]]
 name = "github-actions-expressions"
-version = "0.0.2"
+version = "0.0.3"
 dependencies = [
  "anyhow",
  "itertools",
diff --git a/crates/github-actions-expressions/Cargo.toml b/crates/github-actions-expressions/Cargo.toml
index 9ca6e95c..eda87eb0 100644
--- a/crates/github-actions-expressions/Cargo.toml
+++ b/crates/github-actions-expressions/Cargo.toml
@@ -2,7 +2,7 @@
 name = "github-actions-expressions"
 description = "GitHub Actions expression parser and data types"
 repository = "https://github.com/zizmorcore/zizmor/tree/main/crates/github-actions-expressions"
-version = "0.0.2"
+version = "0.0.3"
 readme = "README.md"
 
 homepage.workspace = true
diff --git a/crates/github-actions-expressions/src/lib.rs b/crates/github-actions-expressions/src/lib.rs
index acff40f7..52fe9298 100644
--- a/crates/github-actions-expressions/src/lib.rs
+++ b/crates/github-actions-expressions/src/lib.rs
@@ -1,24 +1,28 @@
 //! GitHub Actions expression parsing and analysis.
 
 #![forbid(unsafe_code)]
-
-// TODO: Re-enable when #[derive(Parser)] doesn't break this.
-// See: https://github.com/pest-parser/pest/issues/326
-// #![deny(missing_docs)]
+#![deny(missing_docs)]
 
 use crate::context::Context;
 
+use self::parser::{ExprParser, Rule};
 use anyhow::Result;
 use itertools::Itertools;
 use pest::{Parser, iterators::Pair};
-use pest_derive::Parser;
 
 pub mod context;
 
-/// A parser for GitHub Actions' expression language.
-#[derive(Parser)]
-#[grammar = "expr.pest"]
-struct ExprParser;
+// Isolates the ExprParser, Rule and other generated types
+// so that we can do `missing_docs` at the top-level.
+// See: https://github.com/pest-parser/pest/issues/326
+mod parser {
+    use pest_derive::Parser;
+
+    /// A parser for GitHub Actions' expression language.
+    #[derive(Parser)]
+    #[grammar = "expr.pest"]
+    pub struct ExprParser;
+}
 
 /// Represents a function in a GitHub Actions expression.
 ///
@@ -80,6 +84,7 @@ pub enum BinOp {
 /// Unary operations allowed in an expression.
 #[derive(Debug, PartialEq)]
 pub enum UnOp {
+    /// `!expr`
     Not,
 }
 
@@ -98,7 +103,9 @@ pub enum Expr<'src> {
     Star,
     /// A function call.
     Call {
+        /// The function name, e.g. `foo` in `foo()`.
         func: Function<'src>,
+        /// The function's arguments.
         args: Vec<Expr<'src>>,
     },
     /// A context identifier component, e.g. `github` in `github.actor`.
@@ -109,12 +116,20 @@ pub enum Expr<'src> {
     Context(Context<'src>),
     /// A binary operation, either logical or arithmetic.
     BinOp {
+        /// The LHS of the binop.
         lhs: Box<Expr<'src>>,
+        /// The binary operator.
         op: BinOp,
+        /// The RHS of the binop.
         rhs: Box<Expr<'src>>,
     },
     /// A unary operation. Negation (`!`) is currently the only `UnOp`.
-    UnOp { op: UnOp, expr: Box<Expr<'src>> },
+    UnOp {
+        /// The unary operator.
+        op: UnOp,
+        /// The expression to apply the operator to.
+        expr: Box<Expr<'src>>,
+    },
 }
 
 impl<'src> Expr<'src> {