build.rs: Add some documentation to reduce confusion in newcomers

In order to reduce the chance that newcomers to the project are confused by build.rs being at the top level instead of inside src/ add a bunch of documentation comments to explain things. Also since we try and document all our code anyway, provide some internal docs to improve chances of comprehension by future-us.

This closes #203 (closed)