I've tried to maintain a habit of documenting the parameters are the top like this:
# foo:onevalue -- some explanation
# bar:multirow (col1, col2, col3) -- explanation
# baz:onevalue,optional -- more explanation
But I'm afraid I haven't been consistent.
I would really like to make ad_page_contract work with includeable templates, which wouldn't be terribly hard, we'll just have to make it look in the caller's scope instead of in the page form.
If we want people to actually take ad_page_contract seriously, we'd probably need to make it unset all local vars except those you specify.
And if we want people to take it really seriously, but also break existing code, we should change the templating system so it passes variables/properties not by just magically setting them as local variables, but through some other namespace (e.g. an ns_set like the current query variables), which ad_page_contract can read for you.