But the problem is that, as outlined above, your code does not demonstrate how to use parameters to call the file in a Moodle way - it shows how to bypass the Moodle way and retrieve files directly.
Yes, the documentation could be improved - I think it is great that Andy Normore started off the local/filemanager example as a demo of how to use the filemanager and access files within Moodle (I extended it and corrected some of the problems in my version here https://github.com/davosmith/filemanager ). Maybe when I have some spare time, I will look at updating the docs at http://docs.moodle.org/dev/File_API and http://docs.moodle.org/dev/Using_the_File_API_in_Moodle_forms or maybe just provide an extra page with a simple worked example in it. However, there are also lots of examples of how to use the files API inside Moodle core - take a look at the code for mod/resource for a reasonably straightforward example.