Improve inline documentation

[jdevalk]

Every function/method should have a doc block that is simple to read and understand.

Doc blocks should be meaningful

Functions & methods don't properly document the return types.
For example, the edac_filter_by_value function says in the doc block that it returns an array. However, looking at the code, I see that it can return either an array or null. The same thing applies to many, many other functions & methods. Ideally, we should make sure that the functions always return the same type of value - so, for example, the edac_filter_by_value function should return array() instead of null, and then all cases where this function is used should be checked to ensure that they take that into account. If, for some reason, that is not possible, then the least we should do is properly document the return types. Again, a developer shouldn't need to read the whole function to understand it. The doc block should explain what it does, how to use the parameters, and what it returns.

Omit obvious inline docs

Some obvious inline documentation should be omitted. For example, this:

// Return success response.
wp_send_json( 'success' );

It's pretty obvious what it does; there's no reason to document it. It's just noise. Similarly, saying // Update user meta before calling update_user_meta adds no value. It's obvious. Noise should be removed, and more meaningful documentation should be added to the functions themselves. Doc blocks in functions are supposed to help developers understand what a function does without having to read the whole thing. Here, the function's doc block is just a copy of the function's name, and we need to read everything to understand what it does and how.