I've had to guess / ask loads of stupid questions about extensions in 3.1, and now I've got to $request->variable() and I'm having to read the RFC to know how it works.
Either more documentation needs to be written, or it needs to be easier to find.
I'm not going to argue that documentation couldn't be improved (this is a FOSS project after all), but this thread seems quite unhelpful so far in identifying deficiencies. If the docblocks aren't helpful they should be fixed/removed as necessary.
phpbb\request::request::variable() seems straightforward to me. The interface is nearly the same as request_var() in 3.0, except now you can specify REQUEST/GET/POST/COOKIE instead of REQUEST/COOKIE only as in 3.0.
I agree with callumacrae.
I have started working on the new version of my website, based on phpBB 3.1. I don't know much about the source code of phpBB, and sometimes it's pretty hard to really know what the parameter are.
If it can help, I'd be glad to make a list of item that does not seem clear to me as I go on with my work.
The problem might be that the people who wrote the docblock knows the source code of phpBB, and thus understand more easily what they are tring to explain.