Add docstring for `Window::try_new_with_schema`

[Jefffrey]

Is your feature request related to a problem or challenge?

datafusion/datafusion/expr/src/logical_plan/plan.rs

Lines 2546 to 2564 in daeb659

	pub fn try_new_with_schema(
	window_expr: Vec<Expr>,
	input: Arc<LogicalPlan>,
	schema: DFSchemaRef,
	) -> Result<Self> {
	if window_expr.len() != schema.fields().len() - input.schema().fields().len() {
	return plan_err!(
	"Window has mismatch between number of expressions ({}) and number of fields in schema ({})",
	window_expr.len(),
	schema.fields().len() - input.schema().fields().len()
	);
	}
	Ok(Window {
	input,
	window_expr,
	schema,
	})
	}

Introduced by #10850 but we don't have any docs on it to explain when to use this and what it expects from it's inputs. Also would be nice to fix the error message to be more descriptive.

Describe the solution you'd like

Docstring highlighting when to use it (apparently more performant than try_new but need to uphold some invariants regarding the schema as shown by the error check), also update the error message. In #17770 we see an error message appear like:

Error during planning: Window has mismatch between number of expressions (1) and number of fields in schema (0)

For query:

WITH suppliers AS (
  SELECT *
  FROM (VALUES (1, 10.0), (1, 20.0)) AS t(nation, acctbal)
)
SELECT
  ROW_NUMBER() OVER (PARTITION BY nation ORDER BY acctbal DESC) AS rn
FROM suppliers AS s
WHERE acctbal > (
  SELECT AVG(acctbal) FROM suppliers
);

But this doesn't make sense (how is "number of fields in schema" zero?). Especially when you look at the code itself you would probably notice that the input node schema doesn't have zero fields; the zero comes from the subtraction which isn't clearly obvious until you check the code itself.

Describe alternatives you've considered

No response

Additional context

No response

[dqkqd]

take