added a comment - - edited
Thanks Rosie. I didn't check the codechecker/moodlechecker on it, I'm too used to get the smurf file from the integrators. Below, some explanation:
1. http://docs.moodle.org/dev/Coding_style#.40return does not mention that @return has to be the last annotation. The return type external_function_parameters is correct. You can write the class name instead of 'object', it's actually better in my opinion.
2. We promised the web service contributors that we'll backport web service function to 2.3 when possible, so I mention 2.3 yet (I don't know yet if it will pass the integration). I'll change for the right version => 2.3.X.
3. Fixing. As the 'field' parameter is a string and is not an occurrence (it's not a list) I thought it was implicit enough, but I'll add an 'or'
4. http://docs.moodle.org/dev/Coding_style#.40since does not mention anything about placement too.
5. same as 1.
6. same as 2.
7. As it is mentioned in the description of this field "An email address - allow email as root@localhost". PARAM_EMAIL would fail root@localhost email address during the web service return value validation process. To be honest I'm not even sure about the rightness to do any email validation... We would need to check other email field of other external function and comment about that in Moodledocs.
8. The code is correct. Note that is a external_format_value() not a external_value()
4. Thanks for noticing the perf issue Rosie. I myself don't use this kind of logic, at the end we learned about the difference about |= and ||= (the first one test all condition, the second one stop at the first true), it was a good exercice