IMHO you should never reassign variables to different types (except for some very specialized cases). It makes any sort of debugging harder.
It is ok to destroy a variable or set it to false but don't make like in your example an array to a bool.
Returning and printing are different functionalities, so if you are returning data then use @return if printing use @print
I no longer use the type of documentation that you are talking about. Instead, I primarily use TDD (Test Driven Development) with very few inline documentation. The test serve as much better documentation of how the feature set works than most documentation can do. Also, most documentation gets stale or is not consistently updated, which when needed it becomes largely useless.