Enhanced RDoc for filter

[BurdetteLamar]

No description provided.

[kou]

Can we say that "the return value is nothing"?
The current #filter implementation returns an integer but it just so happens that input.each returns integer.
We don't want users to expect #filter returns an integer.

[BurdetteLamar]

I agree that this is weird. We see this in a number of places. Can we return something useful when possible, or nil otherwise?

[kou]

I think that it's enough that we say it in document.
Should we return nil explicitly? If we should return something, #filter should return nil.

[BurdetteLamar]

::filter could return the output CSV object or both CSV objects.
::foreach could return the CSV object.
::parse could return the CSV object.

What the user would do with these is none of our business?

[BurdetteLamar]

Or just nil everywhere we're now returning an integer.

[BurdetteLamar]

This is no longer a doc-only PR.

[BurdetteLamar]

@kou, can you take a look?

[kou]

I don't want to state that returning nil or something is the our spec for now.

In the current our knowledge, we don't have enough reason to state that #filter should return nil, the output CSV object or both CSV objects. We may find enough reason to state that #filter should return XXX in the future. If we state that #filter should return ZZZ now, we need to break backward compatibility.

So I think that we should state that #filter returns nothing or #filter's return value is undefined for now.
What do you think about this?

[BurdetteLamar]

Works for me. I'll remove the nil returns and delete the nil returns from the call-seqs.
Some of them say "thingy or nil"; I'll just say "thingy". OK/

[BurdetteLamar]

Done.

[kou]

Thanks.