[misc] Better documentation, clarified a method behavior and made that behavior consistent between implementations