Is it necessary to warn about the @doc attribute for a private function

In that case, I would either surface it to the documentation of the parent function (the one that calls build_url), or move it to its own public function so I can properly document and test it.

For example, you could mention in the public function that any parameter containing < > # % { } | \ ^ ~ [ ] will be filtered out before building the URL. It may help you focus on the behaviour of the code instead of focusing on the implementation. But I can’t say for sure, I have only part of the context.